Summary

Add an allowlist property that enables developers to define a set of external resources directly accessible by the XML processors.

Problem

The Java XML API and JDK provide two levels of control for accessing external resources: fine-grained control through resolvers, catalogs and the JDK built-in catalog, and broad restrictions via External Access Properties and the built-in catalog's RESOLVE property.

• Fine-Grained Control: Resolvers and Catalogs allow applications to specify access by matching individual URIs. This requires listing every necessary resource, making it tedious and difficult to maintain.

• Broad Restrictions: using properties to manage external access at a higher level. In the API, External Access Properties define allowed or denied protocols, while in the JDK, the jdk.xml.jdkcatalog.resolve property applies an even broader rule — either allowing or blocking all network access.

There is no intermediate level of control that allows applications to selectively permit access to a subset of network resources, such as a trusted domain or local/file resources. This lack of flexibility makes it difficult to quickly restore compatibility after enabling broad restrictions without manually listing every required resource.

Solution

Introduce an allowlist property that enables developers to define a set of allowed resources. This property would supplement the existing access control mechanism, ensuring a balance between security and flexibility. Compared to Fine-Grained Controls such as Catalogs, which require exact System Id or URI matches, this property can be used to permit a subset of network activities, such as access to a trusted domain, without the need to specify each individual resource.

In comparison with the Broad Restrictions such as External Access Properties, which grant or deny access on protocol-level rules (e.g. allowing or blocking all http access), this property enables selective access to specific sources, offering more flexibility without fully opening or closing entire categories of network access.

Feature Details

• A new property jdk.xml.resource.allowlist allowing users to specify URI prefix-based access control
• Support standard and trusted domain entries, e.g. http://www.w3c.org
• Support a select set of resources such as http://www.foo.com/dtds
• Allow referencing local files or embedded resources such as file:/, file:/myapp/dtds, jar:file/

This property provides batch access, allowing users to specify access at an intermediate level between the broad access properties and the fine-grained resolver and catalog feature.

For compatibility, this property provides the flexibility for easily regaining compatibility after enabling the broad-based access restriction without code change (as in the case of a resolver), and having to identify and list every resource required by the application.

Specification

Add an Implementation specific properties: jdk.xml.resource.allowlist.

Property Name: jdk.xml.resource.allowlist

System Property: jdk.xml.resource.allowlist

Description: Specifies a list of allowed network access by defining base URIs such as http://java.sun.com/dtd/. Instructs an XML processor to continue reading resources matching an entry in this list, if the resources have not been resolved by a resolver or catalog.

Base URI: The initial portion of a full URI used to identify a resource. In the context of the allowlist, a URI is considered a match if it starts with one of the listed base URIs. For example, the URI http://java.sun.com/dtd/web-app_2_3.dtd matches the base URI http://java.sun.com or http://java.sun.com/dtd/ in the allowlist.

Value Type: String

Value: A comma-separated list of base URIs. The scheme and host are case insensitive, all other components are case sensitive. http://java.sun.com for example, is equivalent to HTTP://java.sun.com or http://java.Sun.com. http://java.sun.com/dtd/ however, will not match http://java.sun.com/DTD/.
This list may be overridden by using the system property on the commandline or in a user-specified configuration file. Setting it to an empty string unsets the allowlist.

Default Value: http://java.sun.com, http://xmlns.jcp.org, http://www.w3.org, file:/, jar:file:/, jrt:/

This change is documented in the module-summary and jaxp.properties. There are three sections.

Section 1: Rewrite External Resource Resolution Process section

Prior to this change: (refer to https://docs.oracle.com/en/java/javase/24/docs/api/java.xml/module-summary.html#JC_PROCESS)

External Resource Resolution Process with the built-in Catalog

The JDK creates a CatalogResolver with the built-in catalog when needed. This CatalogResolver is used as the default external resource resolver.

XML processors may use resolvers (such as EntityResolver, XMLResolver, and CatalogResolver) to handle external references. In the absence of the user-defined resolvers, the JDK XML processors fall back to the default CatalogResolver to attempt to find a resolution before making a connection to fetch the resources. The fall-back also takes place if a user-defined resolver exists but allows the process to continue when unable to resolve the resource.

If the default CatalogResolver is unable to locate a resource, it may signal the XML processors to continue processing, or skip the resource, or throw a CatalogException. The behavior is configured with the jdk.xml.jdkcatalog.resolve property.

After the change (see attached module-summary_v01.html)

External Resource Resolution Process

The XML processor resolves external resources using the following steps:

• User-defined resolver, such as EntityResolver, XMLResolver, if registered on the XML factory
• CatalogResolver if registered or if a catalog file is provided
• The JDK Built-in Catalog
• Direct fetch

If a resolver successfully resolves the resource, the process ends. Otherwise, the XML processor evaluates the signal returned to decide whether to continue, ignore, or reject the resource.

It continues to the next step if:

• User-defined resolver returns null
• CatalogResolver returns null and the RESOLVE feature is set to continue
• The JDK Built-in Catalog returns null and the jdk.xml.jdkcatalog.resolve property is set to continue

It ignores the resource and returns if:

• User-defined resolver returns an empty source
• CatalogResolver returns null and the RESOLVE feature is set to ignore
• The JDK Built-in Catalog returns null and jdk.xml.jdkcatalog.resolve property is set to continue

It terminates and throws an exception if:

• User-defined resolver throws an exception
• CatalogResolver returns null, the RESOLVE feature is reject, and the resource is not in the jdk.xml.resource.allowlist
• The JDK Built-in Catalog returns null, the jdk.xml.jdkcatalog.resolve property is reject, and the resource is not in the jdk.xml.resource.allowlist
• External Access Properties deny access, and the resource is not in the jdk.xml.resource.allowlist

If no resolver resolves the resource and the signal is continue, the XML processor attempts a direct fetch if:

• The resource is in the jdk.xml.resource.allowlist, or
• External Access Properties allow direct fetch for the relevant type of resources

Section 2

Add a new row to the implementation-specific properties table for the new property, refer to the attached module-summary_v01.html#ALLOWLIST. Below is the diff:

+ * <tr>
+ * <td id="ALLOWLIST">{@systemProperty jdk.xml.resource.allowlist}</td>
+ * <td>Specifies a list of allowed network access by defining base URIs such as
+ * `http://java.sun.com/dtd/`. Instructs an XML processor to continue reading
+ * resources matching an entry in this list, if the resources have not been resolved
+ * by a resolver or catalog.<p>
+ * <b>Base URI</b>: The initial portion of a full URI used to identify a resource.
+ * In the context of the allowlist, a URI is considered a match if it starts with
+ * one of the listed base URIs. For example, the URI `http://java.sun.com/dtd/web-app_2_3.dtd`
+ * matches the base URI `http://java.sun.com` or `http://java.sun.com/dtd/` in the allowlist
+ * </td>
+ * <td style="text-align:center">String</td>
+ * <td rowspan="2">
+ * A comma-separated list of base URIs. The scheme and host are case insensitive,
+ * all other components are case sensitive. {@code http://java.sun.com} for example,
+ * is equivalent to {@code HTTP://java.sun.com} or {@code http://java.Sun.com}.
+ * {@code http://java.sun.com/dtd/} however, will not match {@code http://java.sun.com/DTD}.<br>
+ * The list may be overridden by using the system property on the commandline or
+ * in a user-specified configuration file. Setting it to an empty string unsets the allowlist.
+ * </td>
+ * <td style="text-align:center">{@code http://java.sun.com, http://xmlns.jcp.org, http://www.w3.org, file:/, jar:file:/, jrt:/}</td>
+ * <td style="text-align:center">No</td>
+ * <td style="text-align:center">Yes</td>
+ * <td style="text-align:center">
+ *     <a href="#DOM">DOM</a><br>
+ *     <a href="#SAX">SAX</a><br>
+ *     <a href="#StAX">StAX</a><br>
+ *     <a href="#Validation">Validation</a><br>
+ *     <a href="#Transform">Transform</a>
+ * </td>
+ * <td style="text-align:center"><a href="#Processor">Method 1</a></td>
+ * <td style="text-align:center">25</td>
+ * </tr>

Section 3 Changes to the default configuration file jaxp.properties

 # javax.xml.accessExternalStylesheet="all"
 #
 #
+# XML Resource Access Allow List:
+#
+# A comma-separated list of base URIs. A resource is considered whitelisted if its
+# system Id starts with one of the listed base URIs. If a resource matches the allowlist,
+# it is allowed for a direct fetch, even if a resolver or the External Access Properties
+# would otherwise reject it. The default setting below allows DTDs and XSDs from
+# the listed domains, and files local to the application to be fetched directly.
+#
+# This list may be overridden by using the system property on the commandline or
+# in a user-specified configuration file. Setting it to an empty string unsets
+# the allowlist.
+#
+jdk.xml.resource.allowlist=http://java.sun.com, http://xmlns.jcp.org, http://www.w3.org, file:/, jar:file:/, jrt:/
+#
 # Catalog Properties:
 #
 # The Catalog API defines four features: FILES, PREFER, DEFER and RESOLVE.