Summary

Add a property jdk.xml.resource.access to support grouped XML resource access via domains, wildcards, and protocols.

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(EAPs) 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.

With the deprecation of EAPs (JDK-8357301), there is also a need to fill the gap by providing a mechanism as required by FEATURE_SECURE_PROCESSING(FSP) to regulate broad access permission.

Solution

• Introduce a new JDK specific property
  Add a JDK specific property jdk.xml.resource.access to support both intermediate and broad access controls. This property supplements 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, or broader access such as all of "http" resources.

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

  Feature Details:

• Allow access by a list of hostnames, wildcard domains, and special symbols for both precise and broad control

• A list of hostnames such as w3.org permits access to resources originated from the domains
• Wildcard domains allow all subdomains of the specified domains. For example, *.sun.com allows access to the subdomains of sun.com
• Symbol keyword @local and @remote permits all local and remote resources
• Symbol scheme @file, @jar:file, @jrt, @http and @https permits access to resources of the relevant scheme
• The * wildcard enables unrestricted access

• "" (empty string) disables all access

  This property adheres to the requirement set by FEATURE_SECURE_PROCESSING(FSP). When FSP is explicitly set via an XML factory, this property is set to "" (empty string) to deny all access. By default, and also when FSP is false, this property is set to "*", allowing unrestricted access. Changing FSP from true to false however, have no effect on this property.

  This property also replaces the JDK built-in Catalog's corresponding RESOLVE property jdk.xml.jdkcatalog.resolve, making it the sole property for controlling resource access, other than resolvers and catalogs.

• Deprecate JDK built-in Catalog's RESOLVE property

  jdk.xml.jdkcatalog.resolve, added in JDK 22, was a JDK built-in Catalog specific property extended from the Catalog's RESOLVE property. It was intended to be used as a signal to the main resolution process, when unable to resolve the resource, to either reject or ignore the resource. With the introduction of jdk.xml.resource.access, this property is no longer needed.

Specification

• Add a JDK specific property: jdk.xml.resource.access

  Property Name: jdk.xml.resource.access

  System Property: jdk.xml.resource.access

  Description: Specifies allowed network access through a list of hosts, wildcard domains, and special symbols.

  • Hosts: Grants access to resources from specific hosts. Hostnames correspond to the values returned by URI#getHost
  • Wildcard domains: Grants access to all subdomains of a domain.
  • Special symbols: Grants access to categories of resources using symbols in the format `@[keyword or scheme]`, where:
    
    • keyword: local, remote
    • scheme: file, jar:file, jrt, http, https

    Among them:

    • @local: Allows all local access that is file, jar:file and jrt
    • @remote: Allows remote access by http and https
    • @file: Allows access to file URIs
    • @jar:file: Allows access to jar:file URIs
    • @jrt: Allows access to Java runtime jrt URIs
    • @http: Allows access to http URIs
    • @https: Allows access to https URIs
    • *: Allows access to all resources, both remote (`@remote`) and local (`@local`)
    • "" (empty string): Disallow all resource access

  Example:

  jdk.xml.resource.access = *.sun.com, w3.org, @local

  This configuration permits access to:

  • All subdomains of sun.com, e.g. java.sun.com
  • Resources from w3.org
  • All local file resources

  Value Type: String

  Value: A comma-separated list of hosts, wildcard domains, and special symbols, case insensitive.

  Default Value: *

• Deprecate JDK built-in Catalog's RESOLVE property

  Marked jdk.xml.jdkcatalog.resolve as Deprecated, for removal

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 or catalog 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

  The XML processor then will attempt a direct fetch if the resource is allowed by jdk.xml.resource.access.

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

It terminates and throws an exception if:

• User-defined resolver throws an exception
• CatalogResolver returns null, the RESOLVE feature is reject
• The resource is not allowed by jdk.xml.resource.access

Section 2

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

+ * <tr>
+ * <td id="RES_ACCESS">{@systemProperty jdk.xml.resource.access}</td>
+ * <td>Specifies allowed network access through a list of hosts, wildcard domains,
+ * and special symbols.
+ * <ul>
+ *     <li><b>Hosts</b>: Grants access to resources from specific hosts. Hostnames
+ *     correspond to the values returned by {@link URI#getHost()}
+ *     </li>
+ *     <li><b>Wildcard domains</b>: Grants access to all subdomains of a domain.</li>
+ *     <li><b>Special symbols</b>: Grants access to categories of resources using symbols in the format
+ *     {@code @[keyword or scheme]}, where:<br>
+ *     <ul>
+ *         <li><b>keyword</b>: local, remote</li>
+ *         <li><b>scheme</b>: file, jar:file, jrt, http, https</li>
+ *     </ul>
+ *     Among them:
+ *     <ul>
+ *         <li>{@code @local}: Allows all local access that is file, jar:file and jrt</li>
+ *         <li>{@code @remote}: Allows remote access by http and https</li>
+ *         <li>{@code @file}: Allows access to file URIs</li>
+ *         <li>{@code @jar:file}: Allows access to jar:file URIs</li>
+ *         <li>{@code @jrt}: Allows access to Java runtime jrt URIs</li>
+ *         <li>{@code @http}: Allows access to http URIs</li>
+ *         <li>{@code @https}: Allows access to https URIs</li>
+ *         <li>{@code *}: Allows access to all resources, both remote ({@code @remote})
+ *         and local ({@code @local})</li>
+ *         <li>"" (empty string): Disallow all resource access</li>
+ *     </ul>
+ *     </li>
+ * </ul>
+ * Example:
+ * {@snippet :
+ *     jdk.xml.resource.access = *.sun.com, w3.org, @local
+ * }
+ * This configuration permits access to:
+ * <ul>
+ *     <li>All subdomains of sun.com, e.g. java.sun.com</li>
+ *     <li>Resources from w3.org</li>
+ *     <li>All local file resources</li>
+ * </ul>
+ * </td>
+ * <td style="text-align:center">String</td>
+ * <td>
+ * A comma-separated list of hosts, wildcard domains, and special symbols, case insensitive.
+ * </td>
+ * <td style="text-align:center">{@code *}</td>
+ * <td style="text-align:center">""</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

+# XML Resource Access Property:
+#
+# A comma-separated list of of hosts, wildcard domains,and special symbols.
+# Hosts: Grants access to resources from specific hosts. Hostnames correspond to
+# the values returned by URI#getHost()
+# Wildcard domains: Grants access to all subdomains of a domain
+# Special symbols:
+#     @local: Allows all local access that is file, jar:file and jrt
+#     @remote: Allows remote access by http and https
+#     @file: Allows access to file URIs
+#     @jar:file: Allows access to jar:file URIs
+#     @jrt: Allows access to Java runtime jrt URIs
+#     @http: Allows access to http URIs
+#     @https: Allows access to https URIs
+#     *: Allows access to all resources, both remote (@remote) and local (@local)
+#     "" (empty string): Blocks all access
+#
+# Example:
+#    jdk.xml.resource.access = *.sun.com, w3.org, @local
+#
+#    This configuration permits access to:
+#        All subdomains of sun.com, e.g. java.sun.com
+#        Resources from w3.org<
+#        All local file resources
+#
+# The default allows unrestricted access
+jdk.xml.resource.access=*
+#