This is an automated email from the ASF dual-hosted git repository. garydgregory pushed a commit to branch main in repository https://gitbox.apache.org/repos/asf/commons-secure-xml.git
commit 4e3af7cdd4ea753487dc24d4016aa9d905193ea7 Author: Gary Gregory <[email protected]> AuthorDate: Mon Sep 14 17:04:32 2026 -0700 Javadoc --- src/main/javadoc/overview.html | 40 ++++++++++++++++++++-------------------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/src/main/javadoc/overview.html b/src/main/javadoc/overview.html index 73677ed..7c08487 100644 --- a/src/main/javadoc/overview.html +++ b/src/main/javadoc/overview.html @@ -82,7 +82,7 @@ <h1> <p> Defaults are also uneven. The stock JDK SAX and DOM parsers already prevent external entity resolution through <a href="https://docs.oracle.com/en/java/javase/25/docs/api/java.xml/javax/xml/XMLConstants.html#FEATURE_SECURE_PROCESSING";><code>FEATURE_SECURE_PROCESSING</code></a>, - and JAXP 1.5 conformant implementations ship reasonable defaults for most attacks. Others, such as standalone Xerces, Woodstox, or Saxon’s TrAX, need + and implementations conforming to JAXP 1.5 ship reasonable defaults for most attacks. Others, such as standalone Xerces, Woodstox, or Saxon’s TrAX, need further configuration before they reach the same baseline. A library author has no control over which implementation is on the classpath at runtime, so the effective security posture of their code depends on a deployment decision made elsewhere. </p> @@ -90,7 +90,7 @@ <h1> This library provides that baseline. Each <code>org.apache.commons.xml.secure</code> factory call returns a new factory secured by an implementation-specific recipe, so the returned object behaves the same way security-wise regardless of - which JAXP implementation resolved. Security becomes a property of the call, not of the classpath, and there is one place to update when a new securing + which JAXP implementation was resolved. Security becomes a property of the call, not of the classpath, and there is one place to update when a new securing setting becomes available or a default changes. </p> </section> @@ -104,7 +104,7 @@ <h1> <p> Every factory method in <code>org.apache.commons.xml.secure</code> - returns a new, secured factory. Pick the one that matches the API you already use; no other configuration is required. On secured factories an external + returns a new, secured factory. Pick the one that matches the API you already use; no other configuration is required. On secured factories, an external resource reference (DTD, entity, schema, stylesheet) is never fetched: it resolves to empty content, so the parse continues without it (see Configuration below). </p> @@ -115,7 +115,7 @@ <h2>Supported Runtimes</h2> The security guarantees are defined only on the OpenJDK family (see the <a href="../threat_model.html">Threat Model</a>). No version of Android supports <code>FEATURE_SECURE_PROCESSING</code> (so states <a href="https://developer.android.com/reference/javax/xml/parsers/DocumentBuilderFactory#setFeature%28java.lang.String,%20boolean%29";>Android’s - own documentation</a>), so the library secures the platform’s parsers as best-effort. Android’s + own documentation</a>), so the library secures the platform’s parsers on a best-effort basis. Android’s <code>XmlPullParser</code> API is not supported: it is not a JAXP API. </p> @@ -123,7 +123,7 @@ <h2>Supported Runtimes</h2> <section id="supported-implementations"> <h2>Supported Implementations</h2> <p> - Out of the box the library recognizes the stock JDK JAXP implementations, Apache Xerces 2.x, Woodstox, and Saxon-HE. If a factory resolves to an + Out of the box, the library recognizes the stock JDK JAXP implementations, Apache Xerces 2.x, Woodstox, and Saxon-HE. If a factory resolves to an implementation not covered by any bundled securing recipe, every <code>org.apache.commons.xml.secure</code> factory method throws @@ -252,15 +252,15 @@ <h2>Factory Methods</h2> family (Java 13, <a href="https://bugs.openjdk.org/browse/JDK-8223423";>JDK-8223423</a>). </p> <p> - All of these methods work on every supported runtime, including Java 8: - The - <code>newNSInstance</code> - methods enable namespace awareness on their non-NS counterpart, the behavior the JAXP methods are specified to have. - The - <code>newDefaultInstance</code> - methods resolve the platform’s own - <code>newDefaultInstance</code> - at run time and use it wherever the runtime provides one — Java 9 or later, and the Android API levels that ship the method — falling back to - instantiating the JDK’s built-in implementation by class name on Java 8. + All of these methods work on every supported runtime, including Java 8: </p> + <ul> + <li>The <code>newNSInstance</code> methods enable namespace awareness on their non-NS counterparts, + the behavior the JAXP methods are specified to have.</li> + <li>The <code>newDefaultInstance</code> methods resolve the platform’s own <code>newDefaultInstance</code> + at run time and use it wherever the runtime provides one (Java 9 or later, and the Android API levels that ship the method), + falling back to instantiating the JDK’s built-in implementation by class name on Java 8.</li> + </ul> <p> The <code>newDefaultInstance</code> @@ -333,7 +333,7 @@ <h1> configure, so the tightening carries <strong>no security weight</strong> and can be as strict as the application needs: </p> <ul> - <li>Set a stricter feature on the factory, for example <code>http://apache.org/xml/features/disallow-doctype-decl</code> to reject every document + <li>Set a stricter feature on the factory, for example, <code>http://apache.org/xml/features/disallow-doctype-decl</code> to reject every document carrying a DOCTYPE, on implementations that support the feature. </li> <li>Install a resolver that throws. A caller-supplied <a href="https://docs.oracle.com/en/java/javase/25/docs/api/java.xml/org/xml/sax/EntityResolver.html";><code>EntityResolver</code></a>, <a href="https://docs.oracle.com/en/java/javase/25/docs/api/java.xml/javax/xml/stream/XMLResolver.html";><code>XMLResolver</code></a>, <a href="https://docs.oracle.com/en/java/javase/25/docs/api/java.xml/org/w3c/dom/ls/LSResourceResolver.html";><code>LSResourceResolver</code></a> or <a href="https: [...] @@ -343,7 +343,7 @@ <h1> <section id="resolvers"> <h2>Resolvers</h2> <p> - A resolver here serves the opposite purpose it does on a stock JAXP factory. + A resolver here serves the opposite purpose from the one it serves on a stock JAXP factory. There, returning <code>null</code> hands the reference back to the parser, which fetches it; on a secured factory, returning <code>null</code> leaves the reference unresolved, and the securing floor answers it with empty content. @@ -351,7 +351,7 @@ <h2>Resolvers</h2> </p> <p> A resolver is therefore the way to opt a resource back in, - and returning a non-null result is how you say “this one is allowed”. + and returning a non-null result is how you say “this one is allowed.” Your resolver is consulted before the floor and is never replaced by it, and what it returns is honored even where the JAXP 1.5 external-access properties would deny the fetch, because those properties do not apply to a resolved result. @@ -433,7 +433,7 @@ <h2>Resolvers</h2> so the references inside the resource you allowed face the same floor again. A function that cannot accept an empty document in place of what it asked for, <code>unparsed-text()</code> among them, reports an error when the resolver declines rather than returning empty content; - either way the resource is not fetched. + either way, the resource is not fetched. </p> <div class="sourceCode" id="cb9"> <pre class="sourceCode java"> @@ -516,9 +516,9 @@ <h1> </li> </ul> <p> - The first and third defect fail closed — - a legitimately resolved document is denied, never fetched — - so they break resolver-based applications without weakening the securing; + The first and third defects fail closed: + a legitimately resolved document is denied, never fetched. + They therefore break resolver-based applications without weakening the securing; the second fails open and would leave a real fetch channel unguarded. A resolver floor has neither problem: it covers every channel on every supported implementation,
