JEP 185: Restrict Fetching of External XML Resources

OwnerJoe Wang
StatusClosed / Delivered
Componentxml / jaxp
Discussioncore dash libs dash dev at openjdk dot java dot net
Reviewed byAlan Bateman, Lance Andersen
Endorsed byBrian Goetz
Created2013/04/09 20:00
Updated2017/06/14 17:46


Enhance the JAXP APIs to add the ability to restrict the set of network protocols that may be used to fetch external resources.


Define standard properties to restrict the set of network protocols that may be used to fetch external resources. The new properties should work seamlessly with the existing secure-processing feature and with other existing features and properties.


This proposal focuses on the handling of external resources. There is no intent to revamp the existing security architecture, nor to change features and properties that are already supported by the implementation but not specified in the API.


The JAXP secure-processing feature places resource limits on XML processors in order to counter some kinds of denial-of-service attacks. It does not, however, limit the means by which external resources may be fetched, which is also useful when attempting to process XML documents securely. The current JAXP implementation supports implementation-specific properties that can be used to enforce such limitations, but there is a need for a standard way to do this.


JAXP 1.5 adds three new API-level properties to limit external connections to specific, named protocols:

It also adds three corresponding system properties, to provide developers the ability to change the settings without changing code:

Finally, it allows the above properties to be set in the existing configuration file, ${java.home}/lib/, so as to define the behavior for all invocations of the JDK or JRE. The format of entries in the file is property-name=value, for example:


Property values

The value of any of the above properties is a list of protocols, separated by commas. A protocol is the scheme portion of a URI or, in the case of the JAR protocol, jar plus the scheme portion separated by colon. A scheme has the syntax:

scheme = alpha *( alpha | digit | "+" | "-" | "." )
where alpha = a-z and A-Z.

A JAR protocol has the syntax:


Protocols including the keyword jar are case-insensitive. Any whitespace in the value, as defined by Character.isSpaceChar(), is ignored. Examples of protocols are file, http, and jar:file.

Default values: Whether to restrict connections by default is an implementation choice. The options are:

When FEATURE_SECURE_PROCESSING is enabled it is recommended that implementations restrict external connections by default, though this may cause problems for applications that process XML/XSD/XSL with external references.

Granting all access: The keyword all grants permission to use all protocols. For example, setting jdk.xml.accessExternalDTD=all in the file would allow a system to work as before with no restrictions on how external resources are fetched.

Setting properties via the JAXP API

JAXP properties can be set through JAXP factories as follows:

DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
dbf.setAttribute(name, value);

SAXParserFactory spf = SAXParserFactory.newInstance();
SAXParser parser = spf.newSAXParser();
parser.setProperty(name, value);

XMLInputFactory xif = XMLInputFactory.newInstance();
xif.setProperty(name, value);

SchemaFactory schemaFactory = SchemaFactory.newInstance(schemaLanguage);
schemaFactory.setProperty(name, value);

TransformerFactory factory = TransformerFactory.newInstance();
factory.setAttribute(name, value);

Scope and order

javax.xml.XMLConstants#FEATURE_SECURE_PROCESSING is a required feature for XML processors including DOM, SAX, Schema Validation, XSLT and XPath. It is recommended that implementations associate security related features and properties with the feature. When the secure feature is set to true, it requires that implementations limit XML processing to conform to implementation limits. When it is false, it instructs the implementation to process XML without restrictions. For the new properties introduced in JAXP 1.5, it is recommended that when the secure feature is set to true, implementations restrict external connections, and when it is false, allow full access.

Properties specified in the file affect all invocations of the JDK or JRE, and will override the default values, or those that may have been set by FEATURE_SECURE_PROCESSING.

System properties, when set, will affect one invocation only, and will override the default settings or those set in, or those that may have been set by FEATURE_SECURE_PROCESSING.

JAXP properties specified through JAXP factories or the SAXParser API will override the system properties, the file, and also the setting of FEATURE_SECURE_PROCESSING.

The new JAXP properties will have no effect on the constructs they attempt to restrict in the following situations:


New tests will be added to test each scenario. There will also be a new version of the JAXP TCK.

Significant testing will be required to assess whether it is feasible to configure the JDK to restrict connections by default.

Risks and Assumptions

The JAXP 1.5 specification does not specify the default value of the properties. Due to the compatibility impact/risk, JAXP 1.5 will be initially integrated with the default configured to not restrict connections.

The JAXP 1.5 specification requires that the new properties be set to restrict external connections when FEATURE_SECURE_PROCESSING is set to true explicitly. Applications that set FEATURE_SECURE_PROCESSING will likely notice the incompatible behavior and so may need to set the new JAXP properties to override FEATURE_SECURE_PROCESSING.