Add enableLegacyMode() for pre-4.0 interoperability

robrichards · robrichards · commit caced0a54419 · 2026-07-22T07:54:44.000-04:00
Provide a single migration aid on XMLSecurityDSig and XMLSecEnc that restores
document/peer acceptance defaults (DOCTYPE, XPath transforms without count
caps, RSA-1.5 key transport) without undoing always-on cryptographic hardening.
diff --git a/CHANGELOG.txt b/CHANGELOG.txt
@@ -7,9 +7,8 @@ Security Improvements:
   loopback/private/link-local/reserved/CGNAT addresses; disable HTTP redirects
 - Reject a DOCTYPE in decrypted XML (defense against entity-expansion / XXE in
   attacker-crafted encrypted content)
-- Reject a DOCTYPE in documents being signature-verified (locateSignature), the
-  same defense onelogin/php-saml and simplesamlphp ship. Closes the
-  entity-reference signature bypass where an Id="&e;" attribute is resolved by
+- Reject a DOCTYPE in documents being signature-verified (locateSignature). Closes
+  the entity-reference signature bypass where an Id="&e;" attribute is resolved by
   getAttribute() but invisible to the XPath reference lookup (libxml2
   xmlXPathNodeValHash bug, the CVE-2025-23369 root cause), letting verify()
   validate a different node than the application reads. Opt out with
@@ -36,16 +35,15 @@ Security Improvements:
   the supplied key (previously only when $allowedSignatureAlgorithms was set),
   so a mismatch is rejected even on the low-level path. Blocks algorithm
   substitution / key confusion (e.g. downgrading an RSA signature to hmac-sha1
-  so a public key is used as the HMAC secret) (GHSA-m5mw-mr39-66vp)
+  so a public key is used as the HMAC secret)
 - Bound EncryptedKey / RetrievalMethod resolution depth (prevents recursive
   key-reference DoS / memory exhaustion)
-- Reject XPath (REC-xpath-19991116) Transforms during verification by default
-  (GHSA-7mf5-fjj8-mvjc). The transform evaluates a document-supplied XPath
-  expression in validateReference() before any crypto runs, so a crafted
-  expression is a pre-auth CPU denial-of-service; the expression is arbitrary
-  XPath by design and cannot be sanitized. SAML / WS-Security do not use XPath
-  transforms. Opt in with XMLSecurityDSig::$allowXPathTransforms = true. Signing
-  is unaffected
+- Reject XPath (REC-xpath-19991116) Transforms during verification by default.
+  The transform evaluates a document-supplied XPath expression in 
+  validateReference()  before any crypto runs, so a crafted expression is a 
+  pre-auth CPU denial-of-service; the expression is arbitrary XPath by design 
+  and cannot be sanitized. SAML / WS-Security do not use XPath transforms. Opt in
+  with XMLSecurityDSig::$allowXPathTransforms = true. Signing is unaffected
 - Cap XPath transforms (max 5) and namespaces per XPath transform (max 20);
   overridable via $maxXPathTransforms / $maxXPathNamespaces
 - Fail closed on unresolved, external, and duplicate-Id Reference URIs
@@ -62,12 +60,18 @@ Features:
   (Julius Türich and joonlabs)
 - use phpseclib for all crypto (symmetric, RSA-1.5, RSA signatures,
   X.509); OpenSSL extension is now optional
+- Add enableLegacyMode() on XMLSecurityDSig and XMLSecEnc: one call restores
+  pre-4.0 interoperability defaults (accept DOCTYPE, allow XPath transforms
+  without count caps, allow RSA-1.5 key transport). Does not undo always-on
+  cryptographic hardening (algorithm/key binding, uniform decrypt errors,
+  hash_equals, decrypted-XML DOCTYPE rejection, etc.). Temporary migration aid.
 
 Notes:
 - Prefer RSA-OAEP and AES-GCM for new deployments; RSA-1.5 and CBC remain
   for legacy XML Encryption interoperability
 - Always check verify() === 1; use getValidatedNodes() for SAML/WS-Security
 - Do not trust KeyInfo certificates alone — pin or validate against a trust store
+- Prefer secure defaults; use enableLegacyMode() only while migrating peers
 
 12, Dec 2026, 3.1.5
 Security:
diff --git a/README.md b/README.md
@@ -32,6 +32,8 @@ xmlseclibs requires PHP version 8.0 or greater. OpenSSL is optional (phpseclib i
 
 * Documents carrying a `DOCTYPE` are rejected during signature verification (`locateSignature()` / `verifyDocument()`). This closes the entity-reference bypass in which an `Id="&e;"` attribute is resolved by `getAttribute()` but is invisible to the XPath reference lookup (a libxml2 hashing bug, the same root cause as CVE-2025-23369), causing `verify()` to validate a different node than the one your application reads. Set `$objDSig->forbidDoctype = false` only if you fully trust the document source and require DTD support.
 
+* **Legacy interoperability (temporary):** if you must accept documents/peers that rely on pre-4.0 behaviour, call `$objDSig->enableLegacyMode()` and/or `$objenc->enableLegacyMode()` once after construction. That restores the interoperability settings in one place (DOCTYPE allowed on verify, XPath transforms allowed without count caps, RSA-1.5 key transport allowed). It does **not** undo always-on hardening such as SignatureMethod/key binding, uniform decryption errors, or DOCTYPE rejection in *decrypted* XML. Prefer migrating peers and removing the call.
+
 ### Verifying a signature (recommended)
 
 ```php
diff --git a/src/XMLSecEnc.php b/src/XMLSecEnc.php
@@ -132,6 +132,25 @@ public function __construct()
         $this->_resetTemplate();
     }
 
+    /**
+     * Restore pre-4.0 interoperability defaults for XML Encryption decryption.
+     *
+     * Use this only when you must decrypt payloads that use RSA-1.5 key
+     * transport. Prefer migrating senders to RSA-OAEP (and AES-GCM) and then
+     * removing the call.
+     *
+     * This does NOT undo 4.0 oracle / XXE hardening that is always enforced
+     * (uniform decryption error messages, DOCTYPE rejection in decrypted XML,
+     * EncryptedKey recursion depth bound, ISO 10126 pad-length validation).
+     *
+     * @return $this
+     */
+    public function enableLegacyMode()
+    {
+        $this->allowRSA15KeyTransport = true;
+        return $this;
+    }
+
     private function _resetTemplate()
     {
         $this->encdoc = new DOMDocument();
diff --git a/src/XMLSecurityDSig.php b/src/XMLSecurityDSig.php
@@ -132,12 +132,9 @@ class XMLSecurityDSig
      *
      * The XPath Filtering Transform evaluates an arbitrary, document-supplied
      * XPath expression during validateReference() -- before any signature
-     * cryptography runs. A crafted expression (e.g. deeply nested predicates)
-     * can be evaluated at super-linear cost, giving an unauthenticated attacker
-     * a pre-auth CPU denial-of-service (GHSA-7mf5-fjj8-mvjc). The expression is
-     * an arbitrary XPath by design, so it cannot be sanitized without breaking
-     * the feature; the maxXPath* caps only bound the count, not the cost of a
-     * single expression.
+     * cryptography runs. The expression is an arbitrary XPath by design, so it 
+     * cannot be sanitized without breaking the feature.
+     * The maxXPath* caps only bound the count, not the cost of a single expression.
      *
      * SAML and WS-Security do not use XPath transforms, so this defaults to
      * false (reject them on the verification path). Set to true only if you
@@ -227,6 +224,29 @@ public function __construct($prefix='ds')
         $this->sigNode = $sigdoc->documentElement;
     }
 
+    /**
+     * Restore pre-4.0 interoperability defaults for signature verification.
+     *
+     * Use this only when you must accept documents/peers that rely on
+     * behaviours 4.0 rejects by default (DOCTYPE, XPath Filtering Transforms,
+     * uncapped XPath transform counts). Prefer migrating peers and then
+     * removing the call.
+     *
+     * This does NOT weaken cryptographic checks that are always enforced in
+     * 4.0 (SignatureMethod/key algorithm binding, hash_equals compares,
+     * fail-closed Reference handling, unknown C14N rejection).
+     *
+     * @return $this
+     */
+    public function enableLegacyMode()
+    {
+        $this->forbidDoctype = false;
+        $this->allowXPathTransforms = true;
+        $this->maxXPathTransforms = PHP_INT_MAX;
+        $this->maxXPathNamespaces = PHP_INT_MAX;
+        return $this;
+    }
+
     /**
      * Reset the XPathObj to null
      */
@@ -646,39 +666,37 @@ public function processRefNode($refNode)
             if (! empty($arUrl['path']) || ! empty($arUrl['host']) || ! empty($arUrl['scheme'])) {
                 throw new Exception('Reference URI must be a same-document reference');
             }
-            if (empty($arUrl['path'])) {
-                if ($identifier = $arUrl['fragment'] ?? null) {
+            if ($identifier = $arUrl['fragment'] ?? null) {
 
-                    /* This reference identifies a node with the given id by using
-                     * a URI on the form "#identifier". This should not include comments.
-                     */
-                    $includeCommentNodes = false;
+                /* This reference identifies a node with the given id by using
+                 * a URI on the form "#identifier". This should not include comments.
+                 */
+                $includeCommentNodes = false;
 
-                    $xPath = new DOMXPath($refNode->ownerDocument);
-                    if ($this->idNS && is_array($this->idNS)) {
-                        foreach ($this->idNS as $nspf => $ns) {
-                            $xPath->registerNamespace($nspf, $ns);
-                        }
-                    }
-                    $iDlist = '@Id="'.XPath::filterAttrValue($identifier, XPath::DOUBLE_QUOTE).'"';
-                    if (is_array($this->idKeys)) {
-                        foreach ($this->idKeys as $idKey) {
-                            $iDlist .= " or @".XPath::filterAttrName($idKey).'="'.
-                                XPath::filterAttrValue($identifier, XPath::DOUBLE_QUOTE).'"';
-                        }
+                $xPath = new DOMXPath($refNode->ownerDocument);
+                if ($this->idNS && is_array($this->idNS)) {
+                    foreach ($this->idNS as $nspf => $ns) {
+                        $xPath->registerNamespace($nspf, $ns);
                     }
-                    $query = '//*['.$iDlist.']';
-                    $nodeset = $xPath->query($query);
-                    if ($nodeset->length === 0) {
-                        throw new Exception('Reference URI does not identify a node');
-                    }
-                    if ($nodeset->length > 1) {
-                        throw new Exception('Reference URI identifies multiple nodes');
+                }
+                $iDlist = '@Id="'.XPath::filterAttrValue($identifier, XPath::DOUBLE_QUOTE).'"';
+                if (is_array($this->idKeys)) {
+                    foreach ($this->idKeys as $idKey) {
+                        $iDlist .= " or @".XPath::filterAttrName($idKey).'="'.
+                            XPath::filterAttrValue($identifier, XPath::DOUBLE_QUOTE).'"';
                     }
-                    $dataObject = $nodeset->item(0);
-                } else {
-                    $dataObject = $refNode->ownerDocument;
                 }
+                $query = '//*['.$iDlist.']';
+                $nodeset = $xPath->query($query);
+                if ($nodeset->length === 0) {
+                    throw new Exception('Reference URI does not identify a node');
+                }
+                if ($nodeset->length > 1) {
+                    throw new Exception('Reference URI identifies multiple nodes');
+                }
+                $dataObject = $nodeset->item(0);
+            } else {
+                $dataObject = $refNode->ownerDocument;
             }
         } else {
             /* This reference identifies the root node with an empty URI. This should
@@ -980,11 +998,7 @@ public function verify($objKey)
 
         /*
          * Always bind the document's declared SignatureMethod to the algorithm
-         * of the caller-supplied key. Without this, an attacker who controls
-         * the XML can substitute the algorithm (e.g. downgrade an RSA signature
-         * to hmac-sha1) so that the relying party's *public* key material is
-         * used as the HMAC secret, enabling signature forgery (key/algorithm
-         * confusion, GHSA-m5mw-mr39-66vp). The key's algorithm is fixed by the
+         * of the caller-supplied key. The key's algorithm is fixed by the
          * caller -- or, in the locateKey() flow, derived from the same document
          * -- so a mismatch always signals tampering.
          */
@@ -1216,9 +1230,6 @@ public static function staticGet509XCerts($certs, $isPEMFormat=true)
      * and HTTP redirects are disabled so a public URL cannot bounce to an
      * internal one.
      *
-     * NOTE: a small DNS-rebinding TOCTOU window remains because the transport
-     * re-resolves the host; only enable URL fetching with trusted input.
-     *
      * @param string $url
      * @param null|array $options
      * @return string
diff --git a/tests/legacy-mode.phpt b/tests/legacy-mode.phpt
@@ -0,0 +1,89 @@
+--TEST--
+enableLegacyMode() restores pre-4.0 interoperability defaults
+--FILE--
+<?php
+require(dirname(__FILE__) . '/../xmlseclibs.php');
+use RobRichards\XMLSecLibs\XMLSecurityDSig;
+use RobRichards\XMLSecLibs\XMLSecurityKey;
+use RobRichards\XMLSecLibs\XMLSecEnc;
+
+/* --- Signature side --- */
+$dsig = new XMLSecurityDSig();
+print "DSIG_DEFAULT: forbidDoctype=".($dsig->forbidDoctype ? '1' : '0')
+    ." allowXPath=".($dsig->allowXPathTransforms ? '1' : '0')
+    ." maxXF=".$dsig->maxXPathTransforms
+    ." maxXN=".$dsig->maxXPathNamespaces."\n";
+
+$dsig->enableLegacyMode();
+print "DSIG_LEGACY: forbidDoctype=".($dsig->forbidDoctype ? '1' : '0')
+    ." allowXPath=".($dsig->allowXPathTransforms ? '1' : '0')
+    ." maxXF=".($dsig->maxXPathTransforms === PHP_INT_MAX ? 'MAX' : $dsig->maxXPathTransforms)
+    ." maxXN=".($dsig->maxXPathNamespaces === PHP_INT_MAX ? 'MAX' : $dsig->maxXPathNamespaces)."\n";
+
+/* DOCTYPE is accepted after enableLegacyMode(). */
+$signed = file_get_contents(dirname(__FILE__) . '/sign-sha256-rsa-sha256-test.xml');
+$withDoctype = preg_replace(
+    '/(<\?xml[^>]*\?>\n)/',
+    "$1<!DOCTYPE Root [ <!ENTITY e \"anything\"> ]>\n",
+    $signed,
+    1
+);
+$doc = new DOMDocument();
+$doc->loadXML($withDoctype, LIBXML_NOENT);
+$dsig = new XMLSecurityDSig();
+$dsig->enableLegacyMode();
+try {
+    $dsig->locateSignature($doc);
+    print "DSIG_DOCTYPE: accepted\n";
+} catch (Exception $e) {
+    print "DSIG_DOCTYPE: ".$e->getMessage()."\n";
+}
+
+/* --- Encryption side --- */
+$enc = new XMLSecEnc();
+print "ENC_DEFAULT: allowRSA15=".($enc->allowRSA15KeyTransport ? '1' : '0')."\n";
+$enc->enableLegacyMode();
+print "ENC_LEGACY: allowRSA15=".($enc->allowRSA15KeyTransport ? '1' : '0')."\n";
+
+$xml = <<<XML
+<?xml version="1.0"?>
+<Root xmlns="urn:envelope">
+<xenc:EncryptedData xmlns:xenc="http://www.w3.org/2001/04/xmlenc#" xmlns:dsig="http://www.w3.org/2000/09/xmldsig#" Type="http://www.w3.org/2001/04/xmlenc#Content">
+  <xenc:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes256-cbc"/>
+  <dsig:KeyInfo>
+    <xenc:EncryptedKey>
+      <xenc:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-1_5"/>
+      <xenc:CipherData><xenc:CipherValue>QUJD</xenc:CipherValue></xenc:CipherData>
+    </xenc:EncryptedKey>
+  </dsig:KeyInfo>
+  <xenc:CipherData><xenc:CipherValue>QUJD</xenc:CipherValue></xenc:CipherData>
+</xenc:EncryptedData>
+</Root>
+XML;
+$doc = new DOMDocument();
+$doc->loadXML($xml);
+$objenc = new XMLSecEnc();
+$objenc->enableLegacyMode();
+$encData = $objenc->locateEncryptedData($doc);
+$objenc->setNode($encData);
+$objenc->type = $encData->getAttribute("Type");
+try {
+    $objKey = $objenc->locateKey();
+    $objenc->locateKeyInfo($objKey);
+    print "ENC_RSA15: accepted\n";
+} catch (Exception $e) {
+    print "ENC_RSA15: ".$e->getMessage()."\n";
+}
+
+/* enableLegacyMode() returns $this for chaining. */
+$chained = (new XMLSecurityDSig())->enableLegacyMode();
+print "CHAIN: ".(($chained instanceof XMLSecurityDSig && $chained->allowXPathTransforms) ? 'ok' : 'fail')."\n";
+?>
+--EXPECTF--
+DSIG_DEFAULT: forbidDoctype=1 allowXPath=0 maxXF=5 maxXN=20
+DSIG_LEGACY: forbidDoctype=0 allowXPath=1 maxXF=MAX maxXN=MAX
+DSIG_DOCTYPE: accepted
+ENC_DEFAULT: allowRSA15=0
+ENC_LEGACY: allowRSA15=1
+ENC_RSA15: accepted
+CHAIN: ok
