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
The following commit(s) were added to refs/heads/main by this push:
new c00a066 Copy editing (#80)
c00a066 is described below
commit c00a06601b945db6502f463a7b872a084bf11b9b
Author: Elliotte Rusty Harold <[email protected]>
AuthorDate: Tue Sep 1 14:09:14 2026 +0000
Copy editing (#80)
---
pom.xml | 2 +-
src/main/javadoc/overview.html | 45 +++++++++-------------
.../xml/secure/AssociatedStylesheetTest.java | 2 +-
.../commons/xml/secure/AttackTestSupport.java | 4 +-
4 files changed, 23 insertions(+), 30 deletions(-)
diff --git a/pom.xml b/pom.xml
index c234e13..76d7edb 100644
--- a/pom.xml
+++ b/pom.xml
@@ -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>
diff --git a/src/main/javadoc/overview.html b/src/main/javadoc/overview.html
index d3d6aaa..63c844a 100644
--- a/src/main/javadoc/overview.html
+++ b/src/main/javadoc/overview.html
@@ -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>
@@ -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">
@@ -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">
@@ -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">
@@ -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">
@@ -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">
@@ -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">
@@ -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>
@@ -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>
@@ -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>
@@ -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>
diff --git
a/src/test/java/org/apache/commons/xml/secure/AssociatedStylesheetTest.java
b/src/test/java/org/apache/commons/xml/secure/AssociatedStylesheetTest.java
index ce8f7f3..40fbbb9 100644
--- a/src/test/java/org/apache/commons/xml/secure/AssociatedStylesheetTest.java
+++ b/src/test/java/org/apache/commons/xml/secure/AssociatedStylesheetTest.java
@@ -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);
diff --git a/src/test/java/org/apache/commons/xml/secure/AttackTestSupport.java
b/src/test/java/org/apache/commons/xml/secure/AttackTestSupport.java
index 819f7ec..77e5e7d 100644
--- a/src/test/java/org/apache/commons/xml/secure/AttackTestSupport.java
+++ b/src/test/java/org/apache/commons/xml/secure/AttackTestSupport.java
@@ -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>
*/
@@ -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(
