diff options
Diffstat (limited to 'contrib/expat/doc')
| -rw-r--r-- | contrib/expat/doc/Makefile.in | 29 | ||||
| -rw-r--r-- | contrib/expat/doc/reference.html | 146 | ||||
| -rw-r--r-- | contrib/expat/doc/xmlwf.1 | 30 | ||||
| -rw-r--r-- | contrib/expat/doc/xmlwf.xml | 28 |
4 files changed, 198 insertions, 35 deletions
diff --git a/contrib/expat/doc/Makefile.in b/contrib/expat/doc/Makefile.in index 72deb0565d94..13be5107f89b 100644 --- a/contrib/expat/doc/Makefile.in +++ b/contrib/expat/doc/Makefile.in @@ -1,7 +1,7 @@ -# Makefile.in generated by automake 1.16.5 from Makefile.am. +# Makefile.in generated by automake 1.18.1 from Makefile.am. # @configure_input@ -# Copyright (C) 1994-2021 Free Software Foundation, Inc. +# Copyright (C) 1994-2025 Free Software Foundation, Inc. # This Makefile.in is free software; the Free Software Foundation # gives unlimited permission to copy and/or distribute it, @@ -102,6 +102,8 @@ am__make_running_with_option = \ test $$has_opt = yes am__make_dryrun = (target_option=n; $(am__make_running_with_option)) am__make_keepgoing = (target_option=k; $(am__make_running_with_option)) +am__rm_f = rm -f $(am__rm_f_notfound) +am__rm_rf = rm -rf $(am__rm_f_notfound) pkgdatadir = $(datadir)/@PACKAGE@ pkgincludedir = $(includedir)/@PACKAGE@ pkglibdir = $(libdir)/@PACKAGE@ @@ -184,10 +186,9 @@ am__base_list = \ sed '$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;s/\n/ /g' | \ sed '$$!N;$$!N;$$!N;$$!N;s/\n/ /g' am__uninstall_files_from_dir = { \ - test -z "$$files" \ - || { test ! -d "$$dir" && test ! -f "$$dir" && test ! -r "$$dir"; } \ - || { echo " ( cd '$$dir' && rm -f" $$files ")"; \ - $(am__cd) "$$dir" && rm -f $$files; }; \ + { test ! -d "$$dir" && test ! -f "$$dir" && test ! -r "$$dir"; } \ + || { echo " ( cd '$$dir' && rm -f" $$files ")"; \ + $(am__cd) "$$dir" && echo $$files | $(am__xargs_n) 40 $(am__rm_f); }; \ } man1dir = $(mandir)/man1 am__installdirs = "$(DESTDIR)$(man1dir)" @@ -303,8 +304,10 @@ ac_ct_DUMPBIN = @ac_ct_DUMPBIN@ am__include = @am__include@ am__leading_dot = @am__leading_dot@ am__quote = @am__quote@ +am__rm_f_notfound = @am__rm_f_notfound@ am__tar = @am__tar@ am__untar = @am__untar@ +am__xargs_n = @am__xargs_n@ bindir = @bindir@ build = @build@ build_alias = @build_alias@ @@ -442,6 +445,7 @@ ctags CTAGS: cscope cscopelist: @WITH_DISTRIBUTABLE_MANPAGE_TRUE@dist-hook: + distdir: $(BUILT_SOURCES) $(MAKE) $(AM_MAKEFLAGS) distdir-am @@ -507,11 +511,11 @@ install-strip: mostlyclean-generic: clean-generic: - -test -z "$(CLEANFILES)" || rm -f $(CLEANFILES) + -$(am__rm_f) $(CLEANFILES) distclean-generic: - -test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES) - -test . = "$(srcdir)" || test -z "$(CONFIG_CLEAN_VPATH_FILES)" || rm -f $(CONFIG_CLEAN_VPATH_FILES) + -$(am__rm_f) $(CONFIG_CLEAN_FILES) + -test . = "$(srcdir)" || $(am__rm_f) $(CONFIG_CLEAN_VPATH_FILES) maintainer-clean-generic: @echo "This command is intended for maintainers to use" @@ -616,3 +620,10 @@ uninstall-man: uninstall-man1 # Tell versions [3.59,3.63) of GNU make to not export all variables. # Otherwise a system limit (for SysV at least) may be exceeded. .NOEXPORT: + +# Tell GNU make to disable its built-in pattern rules. +%:: %,v +%:: RCS/%,v +%:: RCS/% +%:: s.% +%:: SCCS/s.% diff --git a/contrib/expat/doc/reference.html b/contrib/expat/doc/reference.html index 2b3bd39580a9..d2dded499435 100644 --- a/contrib/expat/doc/reference.html +++ b/contrib/expat/doc/reference.html @@ -52,7 +52,7 @@ <div> <h1> The Expat XML Parser - <small>Release 2.7.1</small> + <small>Release 2.7.3</small> </h1> </div> <div class="content"> @@ -157,6 +157,8 @@ interface.</p> <ul> <li><a href="#XML_SetBillionLaughsAttackProtectionMaximumAmplification">XML_SetBillionLaughsAttackProtectionMaximumAmplification</a></li> <li><a href="#XML_SetBillionLaughsAttackProtectionActivationThreshold">XML_SetBillionLaughsAttackProtectionActivationThreshold</a></li> + <li><a href="#XML_SetAllocTrackerMaximumAmplification">XML_SetAllocTrackerMaximumAmplification</a></li> + <li><a href="#XML_SetAllocTrackerActivationThreshold">XML_SetAllocTrackerActivationThreshold</a></li> <li><a href="#XML_SetReparseDeferralEnabled">XML_SetReparseDeferralEnabled</a></li> </ul> </li> @@ -319,7 +321,7 @@ directions in the next section. Otherwise if you have Microsoft's Developer Studio installed, you can use CMake to generate a <code>.sln</code> file, e.g. <code> -cmake -G"Visual Studio 16 2019" -DCMAKE_BUILD_TYPE=RelWithDebInfo . +cmake -G"Visual Studio 17 2022" -DCMAKE_BUILD_TYPE=RelWithDebInfo . </code>, and build Expat using <code>msbuild /m expat.sln</code> after.</p> <p>Alternatively, you may download the Win32 binary package that @@ -1905,7 +1907,7 @@ struct XML_cp { <p>Sets a handler for element declarations in a DTD. The handler gets called with the name of the element in the declaration and a pointer to a structure that contains the element model. It's the user code's -responsibility to free model when finished with it. See <code> +responsibility to free model when finished with via a call to <code> <a href="#XML_FreeContentModel">XML_FreeContentModel</a></code>. There is no need to free the model from the handler, it can be kept around and freed at a later stage.</p> @@ -2135,8 +2137,8 @@ XML_Size XMLCALL XML_GetCurrentColumnNumber(XML_Parser p); </pre> <div class="fcndef"> -Return the offset, from the beginning of the current line, of -the position. +Return the <em>offset</em>, from the beginning of the current line, of +the position. The first column is reported as <code>0</code>. </div> <h4 id="XML_GetCurrentByteCount">XML_GetCurrentByteCount</h4> @@ -2198,13 +2200,16 @@ XML_SetBillionLaughsAttackProtectionMaximumAmplification(XML_Parser p, returns <code>XML_TRUE</code> upon success and <code>XML_FALSE</code> upon error. </p> - The amplification factor is calculated as .. - <pre> - amplification := (direct + indirect) / direct - </pre> - .. while parsing, whereas - <code>direct</code> is the number of bytes read from the primary document in parsing and - <code>indirect</code> is the number of bytes added by expanding entities and reading of external DTD files, combined. + <p> + Once the <a href="#XML_SetBillionLaughsAttackProtectionActivationThreshold">threshold for activation</a> is reached, + the amplification factor is calculated as .. + </p> + <pre>amplification := (direct + indirect) / direct</pre> + <p> + .. while parsing, whereas + <code>direct</code> is the number of bytes read from the primary document in parsing and + <code>indirect</code> is the number of bytes added by expanding entities and reading of external DTD files, combined. + </p> <p>For a call to <code>XML_SetBillionLaughsAttackProtectionMaximumAmplification</code> to succeed:</p> <ul> @@ -2267,6 +2272,123 @@ XML_SetBillionLaughsAttackProtectionActivationThreshold(XML_Parser p, </p> </div> +<h4 id="XML_SetAllocTrackerMaximumAmplification">XML_SetAllocTrackerMaximumAmplification</h4> +<pre class="fcndec"> +/* Added in Expat 2.7.2. */ +XML_Bool +XML_SetAllocTrackerMaximumAmplification(XML_Parser p, + float maximumAmplificationFactor); +</pre> +<div class="fcndef"> + <p> + Sets the maximum tolerated amplification factor + between direct input and bytes of dynamic memory allocated + (default: <code>100.0</code>) + of parser <code>p</code> to <code>maximumAmplificationFactor</code>, and + returns <code>XML_TRUE</code> upon success and <code>XML_FALSE</code> upon error. + </p> + + <p> + <strong>Note:</strong> + There are three types of allocations that intentionally bypass tracking and limiting: + </p> + <ul> + <li> + application calls to functions + <code><a href="#XML_MemMalloc">XML_MemMalloc</a></code> + and + <code><a href="#XML_MemRealloc">XML_MemRealloc</a></code> + — + <em>healthy</em> use of these two functions continues to be a responsibility + of the application using Expat + —, + </li> + <li> + the main character buffer used by functions + <code><a href="#XML_GetBuffer">XML_GetBuffer</a></code> + and + <code><a href="#XML_ParseBuffer">XML_ParseBuffer</a></code> + (and thus also by plain + <code><a href="#XML_Parse">XML_Parse</a></code>), and + </li> + <li> + the <a href="#XML_SetElementDeclHandler">content model memory</a> + (that is passed to the + <a href="#XML_SetElementDeclHandler">element declaration handler</a> + and freed by a call to + <code><a href="#XML_FreeContentModel">XML_FreeContentModel</a></code>). + </li> + </ul> + + <p> + Once the <a href="#XML_SetAllocTrackerActivationThreshold">threshold for activation</a> is reached, + the amplification factor is calculated as .. + </p> + <pre>amplification := allocated / direct</pre> + <p> + .. while parsing, whereas + <code>direct</code> is the number of bytes read from the primary document in parsing and + <code>allocated</code> is the number of bytes of dynamic memory allocated in the parser hierarchy. + </p> + + <p>For a call to <code>XML_SetAllocTrackerMaximumAmplification</code> to succeed:</p> + <ul> + <li>parser <code>p</code> must be a non-<code>NULL</code> root parser (without any parent parsers) and</li> + <li><code>maximumAmplificationFactor</code> must be non-<code>NaN</code> and greater than or equal to <code>1.0</code>.</li> + </ul> + + <p> + <strong>Note:</strong> + If you ever need to increase this value for non-attack payload, + please <a href="https://github.com/libexpat/libexpat/issues">file a bug report</a>. + </p> + + <p> + <strong>Note:</strong> + Amplifications factors greater than <code>100.0</code> 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). + </p> +</div> + +<h4 id="XML_SetAllocTrackerActivationThreshold">XML_SetAllocTrackerActivationThreshold</h4> +<pre class="fcndec"> +/* Added in Expat 2.7.2. */ +XML_Bool +XML_SetAllocTrackerActivationThreshold(XML_Parser p, + unsigned long long activationThresholdBytes); +</pre> +<div class="fcndef"> + <p> + Sets number of allocated bytes of dynamic memory + needed to activate protection against disproportionate use of RAM + (default: <code>64 MiB</code>) + of parser <code>p</code> to <code>activationThresholdBytes</code>, and + returns <code>XML_TRUE</code> upon success and <code>XML_FALSE</code> upon error. + </p> + + <p> + <strong>Note:</strong> + For types of allocations that intentionally bypass tracking and limiting, please see + <code><a href="#XML_SetAllocTrackerMaximumAmplification">XML_SetAllocTrackerMaximumAmplification</a></code> + above. + </p> + + <p>For a call to <code>XML_SetAllocTrackerActivationThreshold</code> to succeed:</p> + <ul> + <li>parser <code>p</code> must be a non-<code>NULL</code> root parser (without any parent parsers).</li> + </ul> + + <p> + <strong>Note:</strong> + If you ever need to increase this value for non-attack payload, + please <a href="https://github.com/libexpat/libexpat/issues">file a bug report</a>. + </p> +</div> + <h4 id="XML_SetReparseDeferralEnabled">XML_SetReparseDeferralEnabled</h4> <pre class="fcndec"> /* Added in Expat 2.6.0. */ diff --git a/contrib/expat/doc/xmlwf.1 b/contrib/expat/doc/xmlwf.1 index 76aa7e30d074..aa2e9c218007 100644 --- a/contrib/expat/doc/xmlwf.1 +++ b/contrib/expat/doc/xmlwf.1 @@ -5,7 +5,7 @@ \\$2 \(la\\$1\(ra\\$3 .. .if \n(.g .mso www.tmac -.TH XMLWF 1 "March 27, 2025" "" "" +.TH XMLWF 1 "September 24, 2025" "" "" .SH NAME xmlwf \- Determines if an XML document is well-formed .SH SYNOPSIS @@ -88,7 +88,11 @@ supports both. .TP \*(T<\fB\-a\fR\*(T> \fIfactor\fR Sets the maximum tolerated amplification factor -for protection against billion laughs attacks (default: 100.0). +for protection against amplification attacks +like the billion laughs attack +(default: 100.0 +for the sum of direct and indirect output and also +for allocations of dynamic memory). The amplification factor is calculated as .. .nf @@ -97,12 +101,22 @@ The amplification factor is calculated as .. .fi -\&.. while parsing, whereas +\&.. with regard to use of entities and .. + +.nf + + amplification := allocated / direct + +.fi + +\&.. with regard to dynamic memory while parsing. <direct> is the number of bytes read -from the primary document in parsing and +from the primary document in parsing, <indirect> is the number of bytes added by expanding entities and reading of external DTD files, -combined. +combined, and +<allocated> is the total number of bytes of dynamic memory +allocated (and not freed) per hierarchy of parsers. \fINOTE\fR: If you ever need to increase this value for non-attack payload, @@ -110,8 +124,10 @@ please file a bug report. .TP \*(T<\fB\-b\fR\*(T> \fIbytes\fR Sets the number of output bytes (including amplification) -needed to activate protection against billion laughs attacks -(default: 8 MiB). +needed to activate protection against amplification attacks +like billion laughs +(default: 8 MiB for the sum of direct and indirect output, +and 64 MiB for allocations of dynamic memory). This can be thought of as an "activation threshold". \fINOTE\fR: diff --git a/contrib/expat/doc/xmlwf.xml b/contrib/expat/doc/xmlwf.xml index 17e9cf51c191..01316bb16627 100644 --- a/contrib/expat/doc/xmlwf.xml +++ b/contrib/expat/doc/xmlwf.xml @@ -21,7 +21,7 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ <!ENTITY dhfirstname "<firstname>Scott</firstname>"> <!ENTITY dhsurname "<surname>Bronson</surname>"> - <!ENTITY dhdate "<date>March 27, 2025</date>"> + <!ENTITY dhdate "<date>September 24, 2025</date>"> <!-- Please adjust this^^ date whenever cutting a new release. --> <!ENTITY dhsection "<manvolnum>1</manvolnum>"> <!ENTITY dhemail "<email>bronson@rinspin.com</email>"> @@ -158,19 +158,31 @@ supports both. <listitem> <para> Sets the maximum tolerated amplification factor - for protection against billion laughs attacks (default: 100.0). + for protection against amplification attacks + like the billion laughs attack + (default: 100.0 + for the sum of direct and indirect output and also + for allocations of dynamic memory). The amplification factor is calculated as .. </para> <literallayout> amplification := (direct + indirect) / direct </literallayout> <para> - .. while parsing, whereas + .. with regard to use of entities and .. + </para> + <literallayout> + amplification := allocated / direct + </literallayout> + <para> + .. with regard to dynamic memory while parsing. <direct> is the number of bytes read - from the primary document in parsing and + from the primary document in parsing, <indirect> is the number of bytes added by expanding entities and reading of external DTD files, - combined. + combined, and + <allocated> is the total number of bytes of dynamic memory + allocated (and not freed) per hierarchy of parsers. </para> <para> <emphasis>NOTE</emphasis>: @@ -185,8 +197,10 @@ supports both. <listitem> <para> Sets the number of output bytes (including amplification) - needed to activate protection against billion laughs attacks - (default: 8 MiB). + needed to activate protection against amplification attacks + like billion laughs + (default: 8 MiB for the sum of direct and indirect output, + and 64 MiB for allocations of dynamic memory). This can be thought of as an "activation threshold". </para> <para> |