JEP 185: Restrict Fetching of External XML Resources

Summary

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

Goals

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.

Non-Goals

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.

Motivation

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.

Description

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

• javax.xml.XMLConstants.ACCESS_EXTERNAL_DTD: A list of protocols by which external DTDs and external entity references may be accessed.

• javax.xml.XMLConstants.ACCESS_EXTERNAL_SCHEMA: A list of protocols via which external schema references, specified by the schemaLocation attribute of import and include elements, may be resolved.

• javax.xml.XMLConstants.ACCESS_EXTERNAL_STYLESHEET: A list of protocols via which external references specified in stylesheet constructs such as processing instructions, document() functions, import elements, and include elements may be resolved.

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

• javax.xml.accessExternalDTD for ACCESS_EXTERNAL_DTD

• javax.xml.accessExternalSchema for ACCESS_EXTERNAL_SCHEMA

• javax.xml.accessExternalStylesheet for ACCESS_EXTERNAL_STYLESHEET

Finally, it allows the above properties to be set in the existing configuration file, ${java.home}/lib/jaxp.properties, 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:

javax.xml.accessExternalDTD=file,http

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:

jar[:scheme]

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:

• An empty string allows no access;
• A specific protocol, such as file, allows access only via that protocol; or
• The keyword all allows access via all protocols.

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 jaxp.properties 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 jaxp.properties 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 jaxp.properties, 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 jaxp.properties 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:

• When an entity resolver is set on a SAX or DOM parser, an XML resolver is set on a StAX parser, or a URIResolver is set on a transformer.

• When a schema is created explicitly via the SchemaFactory.newSchema() method.

• When external resources are not required. For example, the following features and properties are supported by the reference implementation and may be set as follows to instruct the processor not to load external DTDs or resolve external entities.

  http://apache.org/xml/features/disallow-doctype-decl            true
  http://apache.org/xml/features/nonvalidating/load-external-dtd  false
  http://xml.org/sax/features/external-general-entities           false
  http://xml.org/sax/features/external-parameter-entities         false

Testing

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.

Impact

• Other JDK components: JAX-WS is directly affected. JAX-WS will need to use the new properties to determine whether external resources are to be resolved. Based on our investigation and discussion with other JDK component owners, no other components are directly affected.

• Compatibility: The specification has no compatibility impact. It is up to the implementation to decide whether to maintain compatibility by setting the default to restriction or no restriction.

• I18n/L10n: A few new error messages will need to be translated.

• TCK: A new version of the JAXP TCK will need to be created.