Library JAXP-Based Processing Using ParserPool

In order to take advantage of the secure XML processing defaults of the library, it is strongly recommended that you use our wrapper of JAXP DocumentBuilderFactory. BasicParserPool from our java-support utility library is a thread-safe implementation of a pool of DocumentBuilder instances that provide a secure default configuration, addressing the common classes of XML processing security vulnerabilities.

Basic usage of the pool implementation would be similar to the following:

// One-time instantiation and init for the entire application.
BasicParserPool pp = new BasicParserPool();
pp.initialize();

// Runtime parsing
Document doc = getParserPool().parse(inputStream); // or Reader

Custom JAXP-Based Processing

If you wish to use a different approach to parse XML into a DOM involving your own JAXP DocumentBuilderFactory and DocumentBuilder instances , the following DocumentBuilderFactory settings are strongly recommended and/or mandatory for secure processing:

Set coalescing to true (mandatory as of OpenSAML v3.4, see warning below)
Set ignoringComments to true (mandatory as of OpenSAML v3.4, see warning below)
Set expandEntityReferences to false
Set feature http://javax.xml.XMLConstants/feature/secure-processing to true
Set feature http://apache.org/xml/features/disallow-doctype-decl to true

Custom Non-JAXP-Based Processing

If you wish to use an entirely different, non-JAXP approach for XML processing, it is strongly suggested that you apply configuration settings that implement the equivalent of the custom JAXP guidelines above for the XML processing library or framework in use. You are wholly responsible for determining how to do that. In particular, you must be mindful of the comment and CDATA Node requirement as warned below.

Whichever approach you use, note that as OpenSAML v3.4 you must not surface comment or CDATA Node instances in the parsed DOM. DOM elements containing either comment or CDATA Node children will be rejected by the OpenSAML unmarshalling framework, resulting in a thrown UnmarshallingException.