org.apache.xml.security.utils
Class XMLUtils

java.lang.Object
  |
  +--org.apache.xml.security.utils.XMLUtils

public class XMLUtils

extends java.lang.Object

DOM and XML accessibility and comfort functions.

Author:

Christian Geuer-Pollmann

Field Summary

static java.lang.String

randomNSprefix Prefix for random namespaces.

Method Summary

static void	addReturnToElement(org.w3c.dom.Element e) Method addReturnToElement
static void	addReturnToElement(ElementProxy elementProxy) Method addReturnToElement
static void	addReturnToNode(org.w3c.dom.Node n) Method addReturnToNode
static void	circumventBug2650(org.w3c.dom.Document doc) This method spreads all namespace attributes in a DOM document to their children.
protected static java.lang.Class	classForName(java.lang.String className) Worker method to load a class.
static java.util.Set	convertNodelistToSet(org.w3c.dom.NodeList xpathNodeSet) Method convertNodelistToSet
static org.w3c.dom.NodeList	convertSetToNodelist(java.util.Set set) Method convertSetToNodelist
static org.w3c.dom.Attr	createAttr(org.w3c.dom.Document doc, java.lang.String QName, java.lang.String Value, java.lang.String NamespaceURI) Creates Attributes Attr in the given namespace (if possible).
static org.w3c.dom.Element	createDSctx(org.w3c.dom.Document doc, java.lang.String prefix) Method createDSctx
static org.w3c.dom.Element	createDSctx(org.w3c.dom.Document doc, java.lang.String prefix, java.lang.String namespace) Method createDSctx
static org.w3c.dom.Element	createElementFromBigint(org.w3c.dom.Document doc, java.lang.String elementName, java.math.BigInteger bigInteger) Creates an Element from a BigInteger.
static org.w3c.dom.Element	createElementInEncryptionSpace(org.w3c.dom.Document doc, java.lang.String elementName) Creates an Element in the XML Encryption specification namespace.
static org.w3c.dom.Element	createElementInSignatureSpace(org.w3c.dom.Document doc, java.lang.String elementName) Creates an Element in the XML Signature specification namespace.
static boolean	elementIsInEncryptionSpace(org.w3c.dom.Element element, java.lang.String localName) Returns true if the element is in XML Encryption namespace and the local name equals the supplied one.
static boolean	elementIsInSignatureSpace(org.w3c.dom.Element element, java.lang.String localName) Returns true if the element is in XML Signature namespace and the local name equals the supplied one.
static org.w3c.dom.NodeList	elementToNodeList(org.w3c.dom.Node node) Converts a single Node into a NodeList which contains only that Node
protected static java.lang.ClassLoader	findClassLoader() Worker method to figure out which ClassLoader to use.
static java.util.Vector	getAncestorElements(org.w3c.dom.Node ctxNode) Returns all ancestor elements of a given node up to the document element
static java.util.Vector	getAncestorElements(org.w3c.dom.Node ctxNode, org.w3c.dom.Node rootElement) Returns all ancestor elements of a given node up to the given root element
static java.math.BigInteger	getBigintFromElement(org.w3c.dom.Element element) Fetches a base64-encoded BigInteger from an Element.
static byte[]	getBytesFromElement(org.w3c.dom.Element element) Fetches base64-encoded byte[] data from an Element.
static org.w3c.dom.Element	getDirectChild(org.w3c.dom.Element parentElement, java.lang.String childLocalName, java.lang.String childNamespaceURI) Method getDirectChild
static org.w3c.dom.NodeList	getDirectChildrenElements(org.w3c.dom.Element parentElement) Method getDirectChildrenElements
static java.lang.String	getFullTextChildrenFromElement(org.w3c.dom.Element element) Method getFullTextChildrenFromElement
static java.lang.String	getNodeTypeString(org.w3c.dom.Node n) Method getNodeTypeString
static java.lang.String	getNodeTypeString(short nodeType) Transforms org.w3c.dom.Node.XXX_NODE NodeType values into Strings.
static org.w3c.dom.Document	getOwnerDocument(org.w3c.dom.Node node) This method returns the owner document of a particular node.
static java.lang.String	getRandomNamespacePrefix() This method creates a random String like http://www.xmlsecurity.org/NS#randomval8dcc/C2qwxFukXjJhS7W1xvHHq4Z that will be used for registering the here() function in a specific namespace.
static java.lang.String	getXalanVersion() Method getXalanVersion
static java.lang.String	getXercesVersion() Method getXercesVersion
static java.lang.String	getXPath(org.w3c.dom.Node n) Simple tool to return the position of a particular node in an XPath like String.
static void	guaranteeThatElementInEncryptionSpace(org.w3c.dom.Element element, java.lang.String localName) Verifies that the given Element is in the XML Encryption namespace EncryptionConstants.EncryptionSpecNS and that the local name of the Element matches the supplied on.
static void	guaranteeThatElementInSignatureSpace(org.w3c.dom.Element element, java.lang.String localName) Verifies that the given Element is in the XML Signature namespace Constants.SignatureSpecNS and that the local name of the Element matches the supplied on.
static void	outputDOM(org.w3c.dom.Node contextNode, java.io.OutputStream os) Outputs a DOM tree to an OutputStream.
static void	outputDOM(org.w3c.dom.Node contextNode, java.io.OutputStream os, boolean addPreamble) Outputs a DOM tree to an OutputStream.
static void	outputDOM(org.w3c.dom.Node contextNode, java.lang.String filename) Outputs a DOM tree to a file.
static void	outputDOMc14nWithComments(org.w3c.dom.Node contextNode, java.io.OutputStream os) Serializes the contextNode into the OutputStream, but supresses all Exceptions.
static void	setAttr(org.w3c.dom.Element elem, java.lang.String QName, java.lang.String Value) Sets the Attribute QName with Value in Element elem.
static void	spitOutVersions(org.apache.log4j.Category cat) Method spitOutVersions

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

randomNSprefix

public static final java.lang.String randomNSprefix

Prefix for random namespaces.

See Also:

getRandomNamespacePrefix(), Constant Field Values

Method Detail

getXalanVersion

public static java.lang.String getXalanVersion()

Method getXalanVersion

getXercesVersion

public static java.lang.String getXercesVersion()

Method getXercesVersion

classForName

protected static java.lang.Class classForName(java.lang.String className)
                                       throws java.lang.ClassNotFoundException

Worker method to load a class. Factor out loading classes for future use and JDK differences. Copied from javax.xml.*.FactoryFinder

Parameters:

className - name of class to load from an appropriate classLoader

Returns:

the class asked for

Throws:

java.lang.ClassNotFoundException

findClassLoader

protected static java.lang.ClassLoader findClassLoader()
                                                throws java.lang.ClassNotFoundException

Worker method to figure out which ClassLoader to use. For JDK 1.2 and later use the context ClassLoader. Copied from javax.xml.*.FactoryFinder

Returns:

the appropriate ClassLoader

Throws:

java.lang.ClassNotFoundException

spitOutVersions

public static void spitOutVersions(org.apache.log4j.Category cat)

Method spitOutVersions

Parameters:

cat -

getNodeTypeString

public static java.lang.String getNodeTypeString(short nodeType)

Transforms org.w3c.dom.Node.XXX_NODE NodeType values into Strings.

Parameters:

nodeType - as taken from the Node.getNodeType() function

Returns:

the String value.

See Also:

Node.getNodeType()

getNodeTypeString

public static java.lang.String getNodeTypeString(org.w3c.dom.Node n)

Method getNodeTypeString

Parameters:

n -

getAncestorElements

public static java.util.Vector getAncestorElements(org.w3c.dom.Node ctxNode)

Returns all ancestor elements of a given node up to the document element

Parameters:

ctxNode -

getAncestorElements

public static java.util.Vector getAncestorElements(org.w3c.dom.Node ctxNode,
                                                   org.w3c.dom.Node rootElement)

Returns all ancestor elements of a given node up to the given root element

Parameters:

ctxNode -

rootElement -

getDirectChildrenElements

public static org.w3c.dom.NodeList getDirectChildrenElements(org.w3c.dom.Element parentElement)

Method getDirectChildrenElements

Parameters:

parentElement -

getDirectChild

public static org.w3c.dom.Element getDirectChild(org.w3c.dom.Element parentElement,
                                                 java.lang.String childLocalName,
                                                 java.lang.String childNamespaceURI)

Method getDirectChild

Parameters:

parentElement -

childLocalName -

childNamespaceURI -

outputDOM

public static void outputDOM(org.w3c.dom.Node contextNode,
                             java.lang.String filename)
                      throws java.io.FileNotFoundException

Outputs a DOM tree to a file.

Parameters:

contextNode - root node of the DOM tree

filename - the file name

Throws:

java.io.FileNotFoundException

outputDOM

public static void outputDOM(org.w3c.dom.Node contextNode,
                             java.io.OutputStream os)

Outputs a DOM tree to an OutputStream.

Parameters:

contextNode - root node of the DOM tree

os - the OutputStream

outputDOM

public static void outputDOM(org.w3c.dom.Node contextNode,
                             java.io.OutputStream os,
                             boolean addPreamble)

Outputs a DOM tree to an OutputStream. If an Exception is thrown during execution, it's StackTrace is output to System.out, but the Exception is not re-thrown.

Parameters:

contextNode - root node of the DOM tree

os - the OutputStream

addPreamble -

outputDOMc14nWithComments

public static void outputDOMc14nWithComments(org.w3c.dom.Node contextNode,
                                             java.io.OutputStream os)

Serializes the contextNode into the OutputStream, but supresses all Exceptions.
NOTE: This should only be used for debugging purposes, NOT in a production environment; this method ignores all exceptions, so you won't notice if something goes wrong. If you're asking what is to be used in a production environment, simply use the code inside the try{} statement, but handle the Exceptions appropriately.

Parameters:

contextNode -

os -

elementToNodeList

public static org.w3c.dom.NodeList elementToNodeList(org.w3c.dom.Node node)

Converts a single Node into a NodeList which contains only that Node

Parameters:

node - the Node

Returns:

the NodeList

createAttr

public static org.w3c.dom.Attr createAttr(org.w3c.dom.Document doc,
                                          java.lang.String QName,
                                          java.lang.String Value,
                                          java.lang.String NamespaceURI)

Creates Attributes Attr in the given namespace (if possible). If the namespace is empty, only the QName is used.

Parameters:

doc - the generator (factory) Document

QName - the QName of the Attr

Value - the String value of the Attr

NamespaceURI - the namespace for the Attr

Returns:

the Attr

setAttr

public static void setAttr(org.w3c.dom.Element elem,
                           java.lang.String QName,
                           java.lang.String Value)

Sets the Attribute QName with Value in Element elem.

Parameters:

elem - the Element which has to contain the Attribute

QName - the QName of the Attribute

Value - the value of the Attribute

createElementFromBigint

public static org.w3c.dom.Element createElementFromBigint(org.w3c.dom.Document doc,
                                                          java.lang.String elementName,
                                                          java.math.BigInteger bigInteger)
                                                   throws XMLSignatureException

Creates an Element from a BigInteger. The BigInteger is base64-encoded and put into the Element with a given name. See Section 4.0.1 The ds:CryptoBinary Simple Type: This specification defines the ds:CryptoBinary simple type for representing arbitrary-length integers (e.g. "bignums") in XML as octet strings. The integer value is first converted to a "big endian" bitstring. The bitstring is then padded with leading zero bits so that the total number of bits == 0 mod 8 (so that there are an integral number of octets). If the bitstring contains entire leading octets that are zero, these are removed (so the high-order octet is always non-zero). This octet string is then base64 [MIME] encoded. (The conversion from integer to octet string is equivalent to IEEE 1363's I2OSP [1363] with minimal length).

Parameters:

doc - the factory Document

elementName - the name of the Element

bigInteger - the BigInteger wo be inserted

Returns:

the Element

Throws:

XMLSignatureException - if bigInteger is not positive

getFullTextChildrenFromElement

public static java.lang.String getFullTextChildrenFromElement(org.w3c.dom.Element element)

Method getFullTextChildrenFromElement

Parameters:

element -

getBigintFromElement

public static java.math.BigInteger getBigintFromElement(org.w3c.dom.Element element)
                                                 throws XMLSignatureException

Fetches a base64-encoded BigInteger from an Element.

Parameters:

element - the Element

Returns:

the BigInteger

Throws:

XMLSignatureException - if Element has not exactly one Text child

getBytesFromElement

public static byte[] getBytesFromElement(org.w3c.dom.Element element)
                                  throws XMLSignatureException

Fetches base64-encoded byte[] data from an Element.

Parameters:

element -

Returns:

the byte[] data

Throws:

XMLSignatureException - if Element has not exactly one Text child

createElementInSignatureSpace

public static org.w3c.dom.Element createElementInSignatureSpace(org.w3c.dom.Document doc,
                                                                java.lang.String elementName)

Creates an Element in the XML Signature specification namespace.

Parameters:

doc - the factory Document

elementName - the local name of the Element

Returns:

the Element

createElementInEncryptionSpace

public static org.w3c.dom.Element createElementInEncryptionSpace(org.w3c.dom.Document doc,
                                                                 java.lang.String elementName)

Creates an Element in the XML Encryption specification namespace.

Parameters:

doc - the factory Document

elementName - the local name of the Element

Returns:

the Element

elementIsInSignatureSpace

public static boolean elementIsInSignatureSpace(org.w3c.dom.Element element,
                                                java.lang.String localName)

Returns true if the element is in XML Signature namespace and the local name equals the supplied one.

Parameters:

element -

localName -

Returns:

true if the element is in XML Signature namespace and the local name equals the supplied one

elementIsInEncryptionSpace

public static boolean elementIsInEncryptionSpace(org.w3c.dom.Element element,
                                                 java.lang.String localName)

Returns true if the element is in XML Encryption namespace and the local name equals the supplied one.

Parameters:

element -

localName -

Returns:

true if the element is in XML Encryption namespace and the local name equals the supplied one

guaranteeThatElementInSignatureSpace

public static void guaranteeThatElementInSignatureSpace(org.w3c.dom.Element element,
                                                        java.lang.String localName)
                                                 throws XMLSignatureException

Verifies that the given Element is in the XML Signature namespace Constants.SignatureSpecNS and that the local name of the Element matches the supplied on.

Parameters:

element - Element to be checked

localName -

Throws:

XMLSignatureException - if element is not in Signature namespace or if the local name does not match

See Also:

Constants.SignatureSpecNS

guaranteeThatElementInEncryptionSpace

public static void guaranteeThatElementInEncryptionSpace(org.w3c.dom.Element element,
                                                         java.lang.String localName)
                                                  throws XMLSecurityException

Verifies that the given Element is in the XML Encryption namespace EncryptionConstants.EncryptionSpecNS and that the local name of the Element matches the supplied on.

Parameters:

element - Element to be checked

localName -

Throws:

XMLSecurityException - if element is not in Encryption namespace or if the local name does not match

See Also:

EncryptionConstants.EncryptionSpecNS

getOwnerDocument

public static org.w3c.dom.Document getOwnerDocument(org.w3c.dom.Node node)

This method returns the owner document of a particular node. This method is necessary because it always returns a Document. Node.getOwnerDocument() returns null if the Node is a Document.

Parameters:

node -

Returns:

the owner document of the node

getRandomNamespacePrefix

public static java.lang.String getRandomNamespacePrefix()

This method creates a random String like http://www.xmlsecurity.org/NS#randomval8dcc/C2qwxFukXjJhS7W1xvHHq4Z that will be used for registering the here() function in a specific namespace. The random string is the Base64 encoded version of a 168 bit SecureRandom value.
This random namespace prefix prevents attackers from inserting malicious here() functions in our namespace. The method caches the valued for subsequent calls during the application run.

Returns:

the random namespace prefix String.

createDSctx

public static org.w3c.dom.Element createDSctx(org.w3c.dom.Document doc,
                                              java.lang.String prefix,
                                              java.lang.String namespace)

Method createDSctx

Parameters:

doc -

prefix -

namespace -

createDSctx

public static org.w3c.dom.Element createDSctx(org.w3c.dom.Document doc,
                                              java.lang.String prefix)

Method createDSctx

Parameters:

doc -

prefix -

addReturnToElement

public static void addReturnToElement(ElementProxy elementProxy)

Method addReturnToElement

Parameters:

elementProxy -

addReturnToElement

public static void addReturnToElement(org.w3c.dom.Element e)

Method addReturnToElement

Parameters:

e -

addReturnToNode

public static void addReturnToNode(org.w3c.dom.Node n)

Method addReturnToNode

Parameters:

n -

convertNodelistToSet

public static java.util.Set convertNodelistToSet(org.w3c.dom.NodeList xpathNodeSet)

Method convertNodelistToSet

Parameters:

xpathNodeSet -

convertSetToNodelist

public static org.w3c.dom.NodeList convertSetToNodelist(java.util.Set set)

Method convertSetToNodelist

Parameters:

set -

circumventBug2650

public static void circumventBug2650(org.w3c.dom.Document doc)

This method spreads all namespace attributes in a DOM document to their children. This is needed because the XML Signature XPath transform must evaluate the XPath against all nodes in the input, even against XPath namespace nodes. Through a bug in XalanJ2, the namespace nodes are not fully visible in the Xalan XPath model, so we have to do this by hand in DOM spaces so that the nodes become visible in XPath space.

Parameters:

doc -

See Also:

Namespace axis resolution is not XPath compliant

getXPath

public static java.lang.String getXPath(org.w3c.dom.Node n)

Simple tool to return the position of a particular node in an XPath like String.

Parameters:

n -