Skip to content

Copy editing #80

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
garydgregory merged 1 commit into from
Sep 1, 2026
Merged

Copy editing #80

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -405,7 +405,7 @@ limitations under the License.
</execution>
</executions>
</plugin>
<!-- jdeps makes Saxon.HE a hard requires; flip it to static (optional). The trailing * keeps the rest. -->
<!-- jdeps makes Saxon.HE a hard requirement; flip it to static (optional). The trailing * keeps the rest. -->
<plugin>
<groupId>org.moditect</groupId>
<artifactId>moditect-maven-plugin</artifactId>
Expand Down
45 changes: 19 additions & 26 deletions src/main/javadoc/overview.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,8 +81,8 @@ <h1>
real work, and duplicating it across projects means every project owns the maintenance burden on its own.</p>
<p>
Defaults are also uneven. The stock JDK SAX and DOM parsers already prevent external entity resolution through
<code>FEATURE_SECURE_PROCESSING</code>
, and JAXP 1.5 conformant implementations ship reasonable defaults for most attacks. Others, such as standalone Xerces, Woodstox, or Saxon’s TrAX, need
<code>FEATURE_SECURE_PROCESSING</code>,
and JAXP 1.5 conformant implementations 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>
Expand Down Expand Up @@ -132,8 +132,7 @@ <h2>Supported Implementations</h2>
</p>
<p>
<strong>DOM Parsing</strong> via
<code>DocumentBuilderFactory</code>
:
<code>DocumentBuilderFactory</code>;
</p>
<div class="sourceCode" id="cb1">
<pre class="sourceCode java">
Expand All @@ -147,8 +146,7 @@ <h2>Supported Implementations</h2>
</div>
<p>
<strong>SAX Parsing</strong> via
<code>SAXParserFactory</code>
:
<code>SAXParserFactory</code>;
</p>
<div class="sourceCode" id="cb2">
<pre class="sourceCode java">
Expand All @@ -161,8 +159,7 @@ <h2>Supported Implementations</h2>
</div>
<p>
<strong>Streaming (StAX) Parsing</strong> via
<code>XMLInputFactory</code>
:
<code>XMLInputFactory</code>:
</p>
<div class="sourceCode" id="cb3">
<pre class="sourceCode java">
Expand All @@ -176,8 +173,7 @@ <h2>Supported Implementations</h2>
</div>
<p>
<strong>XSLT Transforms</strong> via
<code>TransformerFactory</code>
:
<code>TransformerFactory</code>:
</p>
<div class="sourceCode" id="cb4">
<pre class="sourceCode java">
Expand All @@ -194,8 +190,7 @@ <h2>Supported Implementations</h2>
</div>
<p>
<strong>XPath Queries</strong> via
<code>XPathFactory</code>
:
<code>XPathFactory</code>:
</p>
<div class="sourceCode" id="cb5">
<pre class="sourceCode java">
Expand All @@ -212,8 +207,7 @@ <h2>Supported Implementations</h2>
</div>
<p>
<strong>W3C XML Schema Validation</strong> via
<code>SchemaFactory</code>
:
<code>SchemaFactory</code>:
</p>
<div class="sourceCode" id="cb6">
<pre class="sourceCode java">
Expand Down Expand Up @@ -290,8 +284,8 @@ <h2>Stylesheets and Schemas</h2>
or
<code>SAXSource</code>
. A stylesheet also chooses where the transform writes (
<code>xsl:result-document</code>
): the securing governs reads only, so restrict output destinations yourself when running an untrusted stylesheet (see the <a href="threat_model.html">Threat
<code>xsl:result-document</code>):
the securing governs reads only, so restrict output destinations yourself when running an untrusted stylesheet (see the <a href="threat_model.html">Threat
Model</a>).
</p>
</section>
Expand All @@ -301,14 +295,13 @@ <h2>Transformer Handlers and Filters</h2>
The
<code>SAXTransformerFactory</code>
extension methods,
<code>newTransformerHandler(...)</code>
,
<code>newTransformerHandler(...)</code>,
<code>newTemplatesHandler()</code>
and
<code>newXMLFilter(...)</code>
, if reachable by casting the factory from
<code>SecureTransformerFactory.newInstance()</code>
, produce handlers, filters and
<code>newXMLFilter(...)</code>,
if reachable by casting the factory from
<code>SecureTransformerFactory.newInstance()</code>,
produce handlers, filters and
<code>Templates</code>
carrying the same securing as the standard entry points: runtime
<code>document()</code>
Expand All @@ -321,8 +314,8 @@ <h2>Transformer Handlers and Filters</h2>
<h2>Caching and Thread-Safety</h2>
<p>
There is no caching or pooling inside
<code>org.apache.commons.xml.secure</code>
; callers on a hot path are responsible for their own caching. The returned factories inherit the thread-safety properties of the underlying JAXP
<code>org.apache.commons.xml.secure</code>;
callers on a hot path are responsible for their own caching. The returned factories inherit the thread-safety properties of the underlying JAXP
implementation, which in practice means they are not thread-safe. Create a new factory per thread or synchronize externally.
</p>
</section>
Expand Down Expand Up @@ -351,8 +344,8 @@ <h1>
As a temporary debugging measure, set the system property
<code>org.apache.commons.xml.secure.throwOnUnresolved</code>
to
<code>true</code>
: every unresolved external reference is then rejected with the resolution hook’s exception, and the message names the denied resource. The property is
<code>true</code>:
every unresolved external reference is then rejected with the resolution hook’s exception, and the message names the denied resource. The property is
read at resolution time, so it can be toggled on a running application; treat it as a diagnostic switch, not as an application configuration.
</p>
</section>
Expand Down
2 changes: 1 addition & 1 deletion src/test/java/org/apache/commons/xml/secure/AssociatedStylesheetTest.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,7 @@ void secureGetAssociatedStylesheetIgnoresExternalDtdWithCallerReader() throws Ex
@Test
void secureGetAssociatedStylesheetOptsInThroughResolver() throws TransformerConfigurationException {
// A caller resolver is consulted for the href exactly as for any other reference. What comes back names the opted-in stylesheet rather than nothing,
// which is what separates an opt-in from the floored default; the floor still re-parses it through a secure reader, so the shape is its own.
// which is what separates an opt-in from the floored default; the floor still reparses it through a secure reader, so the shape is its own.
final StreamSource opted = new StreamSource(AttackTestSupport.resourceUrl("included.xsl").toString());
final TransformerFactory factory = secureFactory();
factory.setURIResolver((href, base) -> href != null && href.endsWith("included.xsl") ? opted : null);
Expand Down
4 changes: 2 additions & 2 deletions src/test/java/org/apache/commons/xml/secure/AttackTestSupport.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -553,7 +553,7 @@ static void assertSchemaDoesNotLeak(final SchemaFactory factory, final Source xs
/**
* Asserts a secure Schema compilation completes without throwing.
*
* <p>{@link SchemaFactory#newSchema(Source)} via {@link SecureSchemaFactory#newInstance(String)}; use this when the secure contract guarantees the compile
* <p>{@link SchemaFactory#newSchema(Source)} via {@link SecureSchemaFactory#newInstance(String)}; use this when the secure contract guarantees compilation
* succeeds but never resolves the external resource (for example, {@code XERCES_LOAD_EXTERNAL_DTD=false} silently skipping the external subset, with the body's
* undeclared entity reference dropped per XML 1.0 §4.1).</p>
*/
Expand Down Expand Up @@ -727,7 +727,7 @@ static void assertValidatorBlocksOrDoesNotLeak(final String xml) {
* Asserts a secure Validator validation completes without throwing.
*
* <p>{@link Validator#validate(Source)} on a validator from {@link #BENIGN_SCHEMA} compiled via {@link SecureSchemaFactory#newInstance(String)}; use this when the
* secure contract guarantees the validate succeeds but never resolves the external resource.</p>
* secure contract guarantees validation succeeds but never resolves the external resource.</p>
*/
static void assertValidatorDoesNotLeak(final String xml) {
assertParseSucceeds(
Expand Down
Loading