From d6246c31a1238d065b4d9690d3bac740326f6485 Mon Sep 17 00:00:00 2001 From: Sebastian Pipping Date: Wed, 3 Sep 2025 01:28:03 +0200 Subject: [PATCH] docs: Document the two allocation tracking API functions CVE: CVE-2025-59375 Upstream-Status: Backport [https://github.com/libexpat/libexpat/commit/d6246c31a1238d065b4d9690d3bac740326f6485] Signed-off-by: Peter Marko --- doc/reference.html | 116 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 116 insertions(+) diff --git a/doc/reference.html b/doc/reference.html index 89476710..81da4e6c 100644 --- a/doc/reference.html +++ b/doc/reference.html @@ -157,6 +157,8 @@ interface.

@@ -2262,6 +2264,120 @@ XML_SetBillionLaughsAttackProtectionActivationThreshold(XML_Parser p,

+

XML_SetAllocTrackerMaximumAmplification

+
+/* Added in Expat 2.7.2. */
+XML_Bool
+XML_SetAllocTrackerMaximumAmplification(XML_Parser p,
+                                        float maximumAmplificationFactor);
+
+
+

+ Sets the maximum tolerated amplification factor + between direct input and bytes of dynamic memory allocated + (default: 100.0) + of parser p to maximumAmplificationFactor, and + returns XML_TRUE upon success and XML_FALSE upon error. +

+ +

+ Note: + There are three types of allocations that intentionally bypass tracking and limiting: +

+ + +

The amplification factor is calculated as ..

+ 
amplification := allocated / direct
+

+ .. while parsing, whereas + direct is the number of bytes read from the primary document in parsing and + allocated is the number of bytes of dynamic memory allocated in the parser hierarchy. +

+ +

For a call to XML_SetAllocTrackerMaximumAmplification to succeed:

+
    +
  • parser p must be a non-NULL root parser (without any parent parsers) and
    • +
  • maximumAmplificationFactor must be non-NaN and greater than or equal to 1.0.
    • +
+ +

+ Note: + If you ever need to increase this value for non-attack payload, + please file a bug report. +

+ +

+ Note: + Amplifications factors greater than 100 can been observed near the start of parsing + even with benign files in practice. + + So if you do reduce the maximum allowed amplification, + please make sure that the activation threshold is still big enough + to not end up with undesired false positives (i.e. benign files being rejected). +

+
+ +

XML_SetAllocTrackerActivationThreshold

+
+/* Added in Expat 2.7.2. */
+XML_Bool
+XML_SetAllocTrackerActivationThreshold(XML_Parser p,
+                                       unsigned long long activationThresholdBytes);
+
+
+

+ Sets number of allocated bytes of dynamic memory + needed to activate protection against disproportionate use of RAM + (default: 64 MiB) + of parser p to activationThresholdBytes, and + returns XML_TRUE upon success and XML_FALSE upon error. +

+ +

+ Note: + For types of allocations that intentionally bypass tracking and limiting, please see + XML_SetAllocTrackerMaximumAmplification + above. +

+ +

For a call to XML_SetAllocTrackerActivationThreshold to succeed:

+
    +
  • parser p must be a non-NULL root parser (without any parent parsers).
    • +
+ +

+ Note: + If you ever need to increase this value for non-attack payload, + please file a bug report. +

+
+

XML_SetReparseDeferralEnabled

 /* Added in Expat 2.6.0. */