1. Background

        The JAXP secure-processing feature places resource limits on XML processors in order to counter certain type 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 restrictions, but there is a need for a standard way to do so.

       JAXP 1.5 adds three new properties along with their corresponding System Properties to allow users to specify the type of external connections that can or can not be permitted. The property values are a list of protocols. The JAXP processors check if a given external connection is allowed by matching the protocol with those in the list. Processors will attempt to establish the connection if it is on the list, or reject it if not.

       JAXP 1.5 has been integrated into 7u40 and JDK8.

2. External Resources

    XML, Schema and XSLT standards support the following constructs that requires external resources. The default behavior of the JDK XML processors is to make a connection and fetch the external resources as specified.

     1) External DTD: references an external Document Type Definition (DTD), example: <!DOCTYPE root_element SYSTEM "url">
     2) External Entity Reference: refer to external data, syntax: <!ENTITY name SYSTEM "url">
        General entity reference such as the following:
          <?xml version="1.0" standalone="no" ?>
          <!DOCTYPE doc [<!ENTITY otherFile SYSTEM "otherFile.xml">]>
     3) External Parameter Entities, syntax <!ENTITY % name SYSTEM uri>, for example:
           <?xml version="1.0" standalone="no"?>
              <!DOCTYPE doc [
               <!ENTITY % foo SYSTEM "http://www.university.com/student.dtd">
     4) XInclude: include an external inforset in an XML document
     5) Reference to XML Schema components using schemaLocation attribute, Import and Include elements. Example: schemaLocation="http://www.foo.com/schema/bar.xsd"
     6) Combining style sheets using import or include element: syntax: <xsl:include href="include.xsl"/>
     7) xml-stylesheet processing instruction: used to include a stylesheet in an xml document, syntax: <?xml-stylesheet href="foo.xsl" type="text/xsl"?>
     8) XSLT Document() function: used to access nodes in an external XML document, for example, <xsl:variable name="dummy" select="document('DocumentFunc2.xml')"/>.

3. New Properties

   JAXP 1.5 defines three new properties that can be used to regulate whether or not XML processors  resolve external resources as listed above. The properties are:
   -- javax.xml.XMLConstants.ACCESS_EXTERNAL_DTD
   -- javax.xml.XMLConstants.ACCESS_EXTERNAL_SCHEMA

   These API properties have corresponding system properties and jaxp.properties.


   Name: http://javax.xml.XMLConstants/property/accessExternalDTD

   Definition: restrict access to external DTDs, external Entity References to the protocols specified.

   Value: see 3.5 Values of the properties

   Default value: "all",  connection permitted to all protocols.

   System property: javax.xml.accessExternalDTD


   Name: http://javax.xml.XMLConstants/property/accessExternalSchema
   Definition: restrict access to the protocols specified for external reference set by the schemaLocation attribute, Import and Include element.
   Value: see 3.5 Values of the properties
   Default value: "all",  connection permitted to all protocols.
   System property: javax.xml.accessExternalSchema


   Name: http://javax.xml.XMLConstants/property/accessExternalStylesheet

   Definition: restrict access to the protocols specified for external reference set by the stylesheet processing instruction, document function, Import and Include element.

   Value: see 3.5 Values of the properties

   Default value: "all",  connection permitted to all protocols.

   System property: javax.xml.accessExternalStylesheet

3.4. {$java.home}/lib/jaxp.properties

    The above properties can be specified in jaxp.properties to define the behavior for all applications using the Java Runtime. The format is "property-name=[value][,value]*", for example:


   The property-names are the same as those of the System Properties that are: javax.xml.accessExternalDTD, javax.xml.accessExternalSchema, and javax.xml.accessExternalStylesheet.

3.5. Values of the properties

    All of the proposed properties above have values in the same format.

    Value: a list of protocols separated by comma. A protocol is the scheme portion of an URI, or in the case of the JAR protocol, "jar" plus the scheme portion separated by colon. A scheme is defined as:

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

              And the JAR protocol:

             Protocols are case-insensitive. Any whitespaces as defined by Character.isSpaceChar in the value will be ignored. Examples of protocols are file, http, jar:file.

    Default value: the default value is implementation specific. In JAXP 1.5 RI, Java SE 7u40 and Java SE 8, the default value is "all", granting permissions to all protocols.

    Granting all access: the keyword "all" grants permission to all protocols. For example, setting javax.xml.accessExternalDTD=all in jaxp.properties would allow a system to work as before with no restrictions on accessing external DTDs and Entity References.

    Denying any access: an empty string, that is, "", means no permission is granted to any protocol. For example, setting javax.xml.accessExternalDTD="" in jaxp.properties would instruct the JAXP processors to deny any external connections.

4. Scope and order

       javax.xml.XMLConstants#FEATURE_SECURE_PROCESSING (FSP) is a required feature for XML processors including DOM, SAX, Schema Validation, XSLT and XPath.  When set to true, it is recommended that implementations enable access restrictions as defined by the new properties specified above.  For compatibility, JAXP 1.5 does not enable the new restrictions, although FSP is true by default for DOM, SAX and Schema Validation.

For JDK 8, the new accessExternal* properties are proposed to be set to the empty string when FSP is explicitly set.  Note that, this is only the case when FSP is set through the API, e.g. factory.setFeature(FSP, true). Although FSP is true by default for DOM, SAX and Schema Validation it is not treated as if "explicitly" set, JDK 8 therefore does not set restrictions by default.

     Properties specified in the jaxp.properties affect all invocations of the JDK or JRE, and will override their 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 SAXParser will take preference over system properties, the jaxp.properties file, as well as javax.xml.XMLConstants#FEATURE_SECURE_PROCESSING.

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

     a) When there is a resolver and the source returned by the resolver is not null. This applies to entity resolvers that may be set on SAX and DOM parsers, XML resolvers on StAX parsers, LSResourceResolver on SchemaFactory, a Validator or ValidatorHandler, or URIResolver on a transformer.

    b) When a schema is created explicitly by calling SchemaFactory's newSchema method

    c) When external resources are not required. For example, the following features/properties are supported by the reference implementation and may be used to instruct the processor to not load the external DTD 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

5 Relationship with the SecurityManager of the Java platform

     a) The JAXP properties will be checked first before a connection is attempted whether or not a SecurityManager is present. This means that a connection may be blocked even if it is granted permission by the SecurityManager. For example, if the JAXP properties are set to disallow http protocol, they will effectively block any connection attempt even when an application has SocketPermission.

     b) For the purpose of restricting connections, the SecurityManager is at a lower level. Permissions will be checked after the JAXP properties are evaluated. If an application does not have SocketPermission for example, then a SecurityException will be thrown even if the JAXP properties are set to allow http connection.

    c) When SecurityManager is present, the JAXP FEATURE_SECURE_PROCESSING is set to true. This behavior will not turn on the new restrictions.

6. Property Settings in the JDK

    The following table shows the default values and behaviors of the new properties in the JDK.

Values of access properties
Default Value
Set FSP(a)
jaxp.properties system property
API property
no change
override override
change to "" override override override

   (a) Set FSP means setting FEATURE_SECURE_PROCESSING explicitly using JAXP factories' setFeature method.

   (b) The only behavioral difference between 7u40 and JDK8 is that setting FSP will not change accessExternal* properties in 7u40, but will set the value to an empty string in JDK8. Setting FSP is considered opt-in in JDK8.

   (c) The order from left to right in the table reflects the overriding order. For example, if an accessExternal property is set through the API, it overrides any that may have been set by other means.

7. Using the properties

7.1 When to use the properties

         Restrictions to fetching external resources are only needed if applications process untrusted XML contents. Internal systems and applications that do not handle untrusted contents do not need to be concerned with the new restrictions or make any changes. Since 7u40 and JDK8 have no requirement on such restrictions by default, applications shall experience no behavioral change when upgrading to 7u40 and JDK8.

         For applications that do handle untrusted XML input, Schema, or Stylesheet, if there is already existing security measures, such as enabling the Java Security Manager to grant only trusted external connections, or resolving entities using resolvers, there is no need for the new features added in JAXP 1.5.

         However, JAXP 1.5 does provide straight-forward protections for system and applications that run without security manager. For such applications, restrictions may be considered by using the new feature as described in detail below.

7.2 Setting properties through the API

         When changing code is feasible, setting the new properties through JAXP factories or parser is the best way to enable restrictions. The properties can be set through the following interfaces:

     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);

     The following is an example of limiting a DOM parser to local connection only for external DTDs:

    DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
    try {
        dbf.setAttribute({{XMLConstants.ACCESS_EXTERNAL_DTD}}, "file, jar:file");
    } catch (IllegalArgumentException e) {
        //jaxp 1.5 feature not supported

      When code change is possible, and for new development, it is recommended that the new properties be set as demonstrated above. By setting the properties this way, applications can be sure to maintain the desired behavior whether they are deployed to older or newer version of the JDK, or whether the properties are set through System Properties or jaxp.properties.

7.3 Using System Properties

       System properties may be useful if changing code is not feasible.

       If it is desirable to set restrictions for an entire invocation of the JDK/JRE, set the system properties  on the command line; If it is needed for only a portion of the application, the system properties may be set before the section and cleared afterwards. For example, the following code shows how system properties may be used:

      //allow resolution of external schemas

      System.setProperty("javax.xml.accessExternalSchema", "file, http");

       //this setting will affect all processing after it's set
       some processing here

       //after it's done, clear the property

7.4 Using jaxp.properties

         jaxp.properties is a plain configuration file. It is located at ${java.home}/lib/jaxp.properties where java.home is the JRE install directory, e.g., [path to installation directory]/jdk7/jre.

         An external access restriction can be set by adding this line into jaxp.properties file:
         javax.xml.accessExternalStylesheet=file, http

         When this is set, all invocations of the JDK/JRE will observe the restriction with regards to loading external Stylesheet.

         This feature may be useful for systems that do not want to allow any external connection by XML processors, in which case, all three properties may be set to, for example, file only.

8. Error handling

       Since the properties are new to the current release, it is recommended that applications catch exceptions proper to the interface, for example, SAXException in the following example.  Catching the applications may work properly on older releases, for example the sample code contains the following method that detects if the sample is run with a version of the JDK or JAXP implementation that supports the new property:

isNewPropertySupported method
    public boolean isNewPropertySupported() {
       try {
           SAXParserFactory spf = SAXParserFactory.newInstance();
           SAXParser parser = spf.newSAXParser();
           parser.setProperty("http://javax.xml.XMLConstants/property/accessExternalDTD", "file");
       } catch (ParserConfigurationException ex) {
       } catch (SAXException ex) {
           String err = ex.getMessage();
           if (err.indexOf("Property 'http://javax.xml.XMLConstants/property/accessExternalDTD' is not recognized.") > -1)
             //expected, jaxp 1.5 not supported
             return false;
       return true;

     If access to external resources is denied due to the restrictions set by the new properties, an exception will be thrown with an error in the following format:

     [type of construct]: Failed to read [type of construct] "[name of the external resource]", because "[type of restriction]" access is not allowed due to restriction set by the [property name] property.

     For example, if fetching an external DTD is denied by restriction to http protocol such as the following: parser.setProperty("http://javax.xml.XMLConstants/property/accessExternalDTD", "file");
     and if the parser parses an XML file that contains external reference to "http://java.sun.com/dtd/properties.dtd", the error message would look like the following:

            External DTD: Failed to read external DTD ''http://java.sun.com/dtd/properties.dtd'', because ''http'' access is not allowed due to restriction set by the accessExternalDTD property.

7. StAX

       The specification for StAX, JSR 173, does not yet support the new properties. However, StAX in the context of JAXP does include the support of these properties. Setting the new properties is similar to SAX or DOM, but through the XMLInputFactory as follows:

        XMLInputFactory xif = XMLInputFactory.newInstance();
        xif.setProperty("http://javax.xml.XMLConstants/property/accessExternalDTD", "file");

        The existing properties and features specified in the StAX, JSR 173 specification will take preference over the new JAXP properties. The SupportDTD property for example, when set to false, will cause a program to throw exception when an input file contains DTD before it can be parsed. For applications that uses the SupportDTD property to disable DTD therefore, the addition of the new properties shall have no effect.

8. Conclusion

        JAXP 1.5 provides new properties to give controls of fetching external resources to users. The use of the new properties is the same as with other existing properties, except that the properties are provided with corresponding system properties and jaxp.properties so that they can be used for system-wide restrictions or permissions.

9. References

    JSR 206 JAXP 1.5 maintenance review: http://www.jcp.org/en/jsr/detail?id=206

    7u40 Release Notes

    7u40 APIs & Documentation

    JEP 185: http://openjdk.java.net/jeps/185

Terms of Use; Privacy Policy; Copyright ©2013-2017 (revision 20160708.bf2ac18)
Please Confirm