Skip navigation links

Oracle Fusion Middleware XML Security Java API Reference for Oracle Security Developer Tools
11g Release 1 (11.1.1)

E10680-05


oracle.security.xmlsec.dsig
Class XSReference

java.lang.Object
  extended by oracle.security.xmlsec.util.XMLNode
      extended by oracle.security.xmlsec.util.XMLElement
          extended by oracle.security.xmlsec.dsig.ObjectReference
              extended by oracle.security.xmlsec.dsig.XSReference


public class XSReference
extends ObjectReference

XML-DSIG Reference element identifying a local or external data object to be signed.

The following URI attribute values are supported:

Other XPointer URIs are not supported, and non-same-document URLs containing fragments are not recommended for best interoperability results.

The Reference's DigestMethod specifies the message digest algorithm to be used during signature and verification processing. Standard digest algorithm URI constants can be found in XMLURI, including:

An optional Type URI may be used to indicate the type of the referenced data object. This URI should always be used if the Reference points to a Manifest object (see XMLURI.obj_Manifest). Standard object type URI constants can be found in XMLURI, including:

See Also:
XSSignature.createReference()

Nested Class Summary

 

Nested classes/interfaces inherited from class oracle.security.xmlsec.dsig.ObjectReference
ObjectReference.CIDResolver

 

Field Summary

 

Fields inherited from class oracle.security.xmlsec.util.XMLNode
node, systemId

 

Constructor Summary
XSReference(org.w3c.dom.Document owner)
          Creates a new XSReference instance.
XSReference(org.w3c.dom.Document owner, java.lang.String id)
          Creates a new XSReference instance.
XSReference(org.w3c.dom.Document owner, java.lang.String id, java.lang.String uri, java.lang.String type)
          Creates a new XSReference instance.
XSReference(org.w3c.dom.Element element)
          Creates a new XSReference instance from the given Element node.
XSReference(org.w3c.dom.Element element, java.lang.String systemId)
          Creates a new XSReference instance from the given Element node.

 

Method Summary
 void addTransform(XSAlgorithmIdentifier trans)
          Adds a Transform algorithm to the list of Transforms to be applied to the referenced data object.
 void computeDigest()
          Computes the bytes of the DigestValue for this Reference, after dereferencing and applying any specified transforms and/or canonicalization, and puts the resulting digest in this Reference's DigestValue element.
 void computeDigest(byte[] dataObject)
          Computes the bytes of the DigestValue for the given data, after applying any specified transforms and/or canonicalization, and puts the resulting digest in this Reference's DigestValue element.
 void computeDigest(org.w3c.dom.Element dataObject)
          Computes the bytes of the DigestValue for the given data, after applying any specified transforms and/or canonicalization, and puts the resulting digest in this Reference's DigestValue element.
 void computeDigest(java.io.InputStream dataObject)
          Computes the bytes of the DigestValue for the given data, after applying any specified transforms and/or canonicalization, and puts the resulting digest in this Reference's DigestValue element.
 void computeDigest(org.w3c.dom.NodeList dataObject)
          Computes the bytes of the DigestValue for the given data, after applying any specified transforms and/or canonicalization, and puts the resulting digest in this Reference's DigestValue element.
 void computeDigest(java.util.Set dataObject)
          Computes the bytes of the DigestValue for the given data, after applying any specified transforms and/or canonicalization, and puts the resulting digest in this Reference's DigestValue element.
 byte[] getDigestedData()
          Returns the pre digested data (after any Transforms have been applied) that was obtained as a result of calling one of the computeDigest or validate methods.
 XSAlgorithmIdentifier getDigestMethod()
          Returns the digest method for this Reference.
 byte[] getDigestValue()
          Returns the bytes of the digest of this Reference.
 java.lang.String getId()
          Returns the value of the Id attribute of this Reference.
 XSManifest getManifest()
          Returns the Manifest pointed to by this Reference that was obtained as a result of calling one of the validate methods.
 java.lang.String getObjectType()
          Returns the value of the Type attribute identifying the type of the referenced object.
 java.lang.StringBuilder getSignatureDetails()
          Return the digested data for signature and references.
 java.lang.StringBuilder getValidationErrorMessage()
          Return the digested data and related details for failed reference.
static boolean isAscii(byte[] data)
           
 void setDigestMethod(java.lang.String digestMethod)
          Sets the DigestMethod element for this Reference, replacing any existing DigestMethod.
 void setDigestMethod(XSAlgorithmIdentifier digestMethod)
          Sets the DigestMethod element for this Reference, replacing any existing DigestMethod.
 void setDigestValue(byte[] digestValue)
          Sets the bytes of the digest of this Reference in the DigestValue element.
 void setId(java.lang.String id)
          Sets the Id attribute of this Reference.
 void setObjectType(java.lang.String type)
          Sets the Type attribute identifying the type of the referenced object.
 boolean validate(boolean validateManifests)
          Validates the digest for this Reference.
 boolean validate(boolean validateManifests, byte[] dataObject)
          Validates the digest for this Reference, using the given data object's bytes to re-calculate the digest.
 boolean validate(boolean validateManifests, org.w3c.dom.Element dataObject)
          Validates the digest for this Reference, using the given subtree to re-calculate the digest.
 boolean validate(boolean validateManifests, java.io.InputStream dataObject)
          Validates the digest for this Reference, using the given data object's bytes to re-calculate the digest.
 boolean validate(boolean validateManifests, org.w3c.dom.NodeList dataObject)
          Validates the digest for this Reference, using the given data object's node-set to re-calculate the digest.
 boolean validate(boolean validateManifests, java.util.Set dataObject)
          Validates the digest for this Reference, using the given data object's node-set to re-calculate the digest.

 

Methods inherited from class oracle.security.xmlsec.dsig.ObjectReference
dereference, dereference, getTransforms, getURI, setCIDResolver, setURI

 

Methods inherited from class oracle.security.xmlsec.util.XMLElement
addNSPrefixAttr, addNSPrefixAttr, addNSPrefixAttrDefault, addNSPrefixAttrDefault, getAttribute, getAttributeNode, getAttributeNodeNS, getAttributeNS, getChildElementsByTagName, getChildElementsByTagName, getChildElementsByTagNameNS, getChildElementsByTagNameNS, getDefaultNSPrefix, getElement, getElementsByTagName, getElementsByTagNameNS, getTagName, hasAttribute, hasAttributeNS, removeAttribute, removeAttributeNode, removeAttributeNS, setAttribute, setAttributeNode, setAttributeNodeNS, setAttributeNS, setDefaultNSPrefix

 

Methods inherited from class oracle.security.xmlsec.util.XMLNode
appendChild, appendChild, appendTo, cloneNode, getAttributes, getChildNodes, getFirstChild, getLastChild, getLocalName, getNamespaceURI, getNextSibling, getNode, getNodeName, getNodeType, getNodeValue, getOwnerDocument, getParentNode, getPrefix, getPreviousSibling, getSystemId, hasAttributes, hasChildNodes, insertBefore, insertBefore, isSupported, normalize, removeChild, removeChild, replaceChild, replaceChild, setNodeValue, setPrefix, setSystemId, toBytesXML, toStringXML

 

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

 

Constructor Detail

XSReference

public XSReference(org.w3c.dom.Element element)
            throws org.w3c.dom.DOMException
Creates a new XSReference instance from the given Element node.
Parameters:
element - An Element node in the XML document that conforms to the XML-DSIG Reference schema.
Throws:
org.w3c.dom.DOMException

XSReference

public XSReference(org.w3c.dom.Element element,
                   java.lang.String systemId)
            throws org.w3c.dom.DOMException
Creates a new XSReference instance from the given Element node.
Parameters:
element - An Element node in the XML document that conforms to the XML-DSIG Reference schema.
systemId - The URI string system ID for this element.
Throws:
org.w3c.dom.DOMException
Since:
2.0
See Also:
XMLNode.setSystemId(java.lang.String)

XSReference

public XSReference(org.w3c.dom.Document owner)
            throws org.w3c.dom.DOMException
Creates a new XSReference instance.
Parameters:
owner - The owner document of the new XSReference.
Throws:
org.w3c.dom.DOMException

XSReference

public XSReference(org.w3c.dom.Document owner,
                   java.lang.String id)
            throws org.w3c.dom.DOMException
Creates a new XSReference instance.
Parameters:
owner - The owner document of the new XSReference.
id - An optional string ID name for this Reference structure.
Throws:
org.w3c.dom.DOMException

XSReference

public XSReference(org.w3c.dom.Document owner,
                   java.lang.String id,
                   java.lang.String uri,
                   java.lang.String type)
            throws org.w3c.dom.DOMException
Creates a new XSReference instance.
Parameters:
owner - The owner document of the new XSReference.
id - An optional string ID name for this Reference structure.
uri - A URI identifying the data object being referenced.
type - An optional URI identifying the type of the referenced data object.
Throws:
org.w3c.dom.DOMException

Method Detail

setId

public void setId(java.lang.String id)
           throws org.w3c.dom.DOMException
Sets the Id attribute of this Reference.
Parameters:
id - The ID name of this Reference.
Throws:
org.w3c.dom.DOMException

getId

public java.lang.String getId()
Returns the value of the Id attribute of this Reference.
Returns:
A string containing the ID name of this Reference, or null if the attribute is missing.

setObjectType

public void setObjectType(java.lang.String type)
                   throws org.w3c.dom.DOMException
Sets the Type attribute identifying the type of the referenced object.
Parameters:
type - A URI identifying the type of the referenced object.
Throws:
org.w3c.dom.DOMException

getObjectType

public java.lang.String getObjectType()
Returns the value of the Type attribute identifying the type of the referenced object.
Returns:
A URI identifying the type of the referenced object, or null if the attribute is missing.

addTransform

public void addTransform(XSAlgorithmIdentifier trans)
                  throws org.w3c.dom.DOMException
Adds a Transform algorithm to the list of Transforms to be applied to the referenced data object.
Overrides:
addTransform in class ObjectReference
Parameters:
trans - A XSAlgorithmIdentifier instance.
Throws:
org.w3c.dom.DOMException

setDigestMethod

public void setDigestMethod(java.lang.String digestMethod)
                     throws org.w3c.dom.DOMException
Sets the DigestMethod element for this Reference, replacing any existing DigestMethod.
Parameters:
digestMethod - A URI identifying this Reference's digest algorithm.
Throws:
org.w3c.dom.DOMException

setDigestMethod

public void setDigestMethod(XSAlgorithmIdentifier digestMethod)
                     throws org.w3c.dom.DOMException
Sets the DigestMethod element for this Reference, replacing any existing DigestMethod.
Parameters:
digestMethod - A XSAlgorithmIdentifier identifying this Reference's digest algorithm.
Throws:
org.w3c.dom.DOMException

getDigestMethod

public XSAlgorithmIdentifier getDigestMethod()
Returns the digest method for this Reference.
Returns:
A XSAlgorithmIdentifier identifying this Reference's digest algorithm.

setDigestValue

public void setDigestValue(byte[] digestValue)
                    throws org.w3c.dom.DOMException
Sets the bytes of the digest of this Reference in the DigestValue element.
Parameters:
digestValue - A byte array containing this Reference's digest.
Throws:
org.w3c.dom.DOMException

getDigestValue

public byte[] getDigestValue()
                      throws org.w3c.dom.DOMException
Returns the bytes of the digest of this Reference.
Returns:
A newly allocated byte array containing this Reference's digest.
Throws:
org.w3c.dom.DOMException

computeDigest

public void computeDigest()
                   throws ReferenceException,
                          oracle.security.crypto.core.AlgorithmIdentifierException,
                          org.w3c.dom.DOMException
Computes the bytes of the DigestValue for this Reference, after dereferencing and applying any specified transforms and/or canonicalization, and puts the resulting digest in this Reference's DigestValue element.

If the data object is not to be obtained by dereferencing this Reference's URI (e.g., if the URI attribute is absent), use the computeDigest(byte[] input) method.

Throws:
oracle.security.crypto.core.AlgorithmIdentifierException - If an error occurs using this Reference's digest method algorithm.
ReferenceException - If an error occurs retrieving the referenced data object or applying the transforms.
org.w3c.dom.DOMException - If an error occurs adding the DigestValue to the Reference.

computeDigest

public void computeDigest(byte[] dataObject)
                   throws ReferenceException,
                          oracle.security.crypto.core.AlgorithmIdentifierException,
                          org.w3c.dom.DOMException
Computes the bytes of the DigestValue for the given data, after applying any specified transforms and/or canonicalization, and puts the resulting digest in this Reference's DigestValue element.

Use this method if the data object is not to be obtained by dereferencing this Reference's URI. Otherwise, use the computeDigest() method.

Parameters:
dataObject - The bytes of the data object to be digested.
Throws:
oracle.security.crypto.core.AlgorithmIdentifierException - If an error occurs using this Reference's digest method algorithm.
ReferenceException - If an error occurs retrieving the referenced data object or applying the transforms.
org.w3c.dom.DOMException - If an error occurs adding the DigestValue to the Reference.

computeDigest

public void computeDigest(java.io.InputStream dataObject)
                   throws ReferenceException,
                          oracle.security.crypto.core.AlgorithmIdentifierException,
                          org.w3c.dom.DOMException
Computes the bytes of the DigestValue for the given data, after applying any specified transforms and/or canonicalization, and puts the resulting digest in this Reference's DigestValue element.

Use this method if the data object is not to be obtained by dereferencing this Reference's URI. Otherwise, use the computeDigest() method.

Parameters:
dataObject - The bytes of the data object to be digested.
Throws:
oracle.security.crypto.core.AlgorithmIdentifierException - If an error occurs using this Reference's digest method algorithm.
ReferenceException - If an error occurs retrieving the referenced data object or applying the transforms.
org.w3c.dom.DOMException - If an error occurs adding the DigestValue to the Reference.

computeDigest

public void computeDigest(org.w3c.dom.NodeList dataObject)
                   throws ReferenceException,
                          oracle.security.crypto.core.AlgorithmIdentifierException,
                          org.w3c.dom.DOMException
Computes the bytes of the DigestValue for the given data, after applying any specified transforms and/or canonicalization, and puts the resulting digest in this Reference's DigestValue element.

Use this method if the data object is not to be obtained by dereferencing this Reference's URI. Otherwise, use the computeDigest() method.

Parameters:
dataObject - The node-set of the data object to be digested.
Throws:
oracle.security.crypto.core.AlgorithmIdentifierException - If an error occurs using this Reference's digest method algorithm.
ReferenceException - If an error occurs retrieving the referenced data object or applying the transforms.
org.w3c.dom.DOMException - If an error occurs adding the DigestValue to the Reference.

computeDigest

public void computeDigest(java.util.Set dataObject)
                   throws ReferenceException,
                          oracle.security.crypto.core.AlgorithmIdentifierException,
                          org.w3c.dom.DOMException
Computes the bytes of the DigestValue for the given data, after applying any specified transforms and/or canonicalization, and puts the resulting digest in this Reference's DigestValue element.

Use this method if the data object is not to be obtained by dereferencing this Reference's URI. Otherwise, use the computeDigest() method.

Parameters:
dataObject - The node-set of the data object to be digested.
Throws:
oracle.security.crypto.core.AlgorithmIdentifierException - If an error occurs using this Reference's digest method algorithm.
ReferenceException - If an error occurs retrieving the referenced data object or applying the transforms.
org.w3c.dom.DOMException - If an error occurs adding the DigestValue to the Reference.
Since:
2.0

computeDigest

public void computeDigest(org.w3c.dom.Element dataObject)
                   throws ReferenceException,
                          oracle.security.crypto.core.AlgorithmIdentifierException,
                          org.w3c.dom.DOMException
Computes the bytes of the DigestValue for the given data, after applying any specified transforms and/or canonicalization, and puts the resulting digest in this Reference's DigestValue element.

Use this method if the data object is not to be obtained by dereferencing this Reference's URI. Otherwise, use the computeDigest() method.

Parameters:
dataObject - The subtree of the data object to be digested.
Throws:
oracle.security.crypto.core.AlgorithmIdentifierException - If an error occurs using this Reference's digest method algorithm.
ReferenceException - If an error occurs retrieving the referenced data object or applying the transforms.
org.w3c.dom.DOMException - If an error occurs adding the DigestValue to the Reference.
Since:
2.0

validate

public boolean validate(boolean validateManifests)
                 throws ReferenceException
Validates the digest for this Reference.
Parameters:
validateManifests - If true, nested Manifests pointed to by References will have their enclosed References validated as well.
Returns:
true if the digest is valid. Returns false if the digest is invalid, or if it cannot be validated because the URI attribute is absent.
Throws:
ReferenceException - If an error occurs retrieving the referenced data object, applying the transforms or computing the digest value.

validate

public boolean validate(boolean validateManifests,
                        byte[] dataObject)
                 throws ReferenceException
Validates the digest for this Reference, using the given data object's bytes to re-calculate the digest.
Parameters:
validateManifests - If true, nested Manifests pointed to by References will have their enclosed References validated as well.
dataObject - The bytes of the data object to be digested, if the data is not to be obtained by dereferencing this Reference's URI (e.g., the URI attribute is absent).
Returns:
true if the digest is valid. Returns false if the digest is invalid, or if it cannot be validated because the URI attribute is absent and the data object's bytes are not provided.
Throws:
ReferenceException - If an error occurs retrieving the referenced data object, applying the transforms or computing the digest value.

validate

public boolean validate(boolean validateManifests,
                        java.io.InputStream dataObject)
                 throws ReferenceException
Validates the digest for this Reference, using the given data object's bytes to re-calculate the digest.
Parameters:
validateManifests - If true, nested Manifests pointed to by References will have their enclosed References validated as well.
dataObject - The bytes of the data object to be digested, if the data is not to be obtained by dereferencing this Reference's URI (e.g., the URI attribute is absent).
Returns:
true if the digest is valid. Returns false if the digest is invalid, or if it cannot be validated because the URI attribute is absent and the data object's bytes are not provided.
Throws:
ReferenceException - If an error occurs retrieving the referenced data object, applying the transforms or computing the digest value.

validate

public boolean validate(boolean validateManifests,
                        org.w3c.dom.NodeList dataObject)
                 throws ReferenceException
Validates the digest for this Reference, using the given data object's node-set to re-calculate the digest.
Parameters:
validateManifests - If true, nested Manifests pointed to by References will have their enclosed References validated as well.
dataObject - The node-set of the data object to be digested, if the data is not to be obtained by dereferencing this Reference's URI (e.g., the URI attribute is absent).
Returns:
true if the digest is valid. Returns false if the digest is invalid, or if it cannot be validated because the URI attribute is absent and the data object's nodes-set is not provided.
Throws:
ReferenceException - If an error occurs retrieving the referenced data object, applying the transforms or computing the digest value.

validate

public boolean validate(boolean validateManifests,
                        java.util.Set dataObject)
                 throws ReferenceException
Validates the digest for this Reference, using the given data object's node-set to re-calculate the digest.
Parameters:
validateManifests - If true, nested Manifests pointed to by References will have their enclosed References validated as well.
dataObject - The node-set of the data object to be digested, if the data is not to be obtained by dereferencing this Reference's URI (e.g., the URI attribute is absent).
Returns:
true if the digest is valid. Returns false if the digest is invalid, or if it cannot be validated because the URI attribute is absent and the data object's nodes-set is not provided.
Throws:
ReferenceException - If an error occurs retrieving the referenced data object, applying the transforms or computing the digest value.
Since:
2.0

validate

public boolean validate(boolean validateManifests,
                        org.w3c.dom.Element dataObject)
                 throws ReferenceException
Validates the digest for this Reference, using the given subtree to re-calculate the digest.
Parameters:
validateManifests - If true, nested Manifests pointed to by References will have their enclosed References validated as well.
dataObject - The subtree which is obtained by resolving the URI. If null, the URI will be dereferenced and transforms applies on that, otherwise the URI dereferencing step will be skipped, and transforms will be applied to the passed in subtree
Returns:
true if the digest is valid. Returns false if the digest is invalid, or if it cannot be validated because the URI attribute is absent and the data object's subtree is not provided.
Throws:
ReferenceException - If an error occurs retrieving the referenced data object, applying the transforms or computing the digest value.

getDigestedData

public byte[] getDigestedData()
Returns the pre digested data (after any Transforms have been applied) that was obtained as a result of calling one of the computeDigest or validate methods. Unless you set xml.debug.digest or xml.debug.verify this will return null
Returns:
The octets of the referenced data object, after any Transforms and/or XML canonicalization have been applied. Returns null if computeDigest() or validate has not yet been invoked for this XSReference.
See Also:
computeDigest(), computeDigest(byte[] dataObject), validate(boolean validateManifests), validate(boolean validateManifests, byte[] dataObject)

getManifest

public XSManifest getManifest()
Returns the Manifest pointed to by this Reference that was obtained as a result of calling one of the validate methods.
Returns:
An XSManifest object, or null if this Reference does not deference to a Manifest, or if validate has not yet been invoked for this XSReference.
Since:
2.0
See Also:
validate(boolean validateManifests), validate(boolean validateManifests, byte[] dataObject)

isAscii

public static boolean isAscii(byte[] data)

getValidationErrorMessage

public java.lang.StringBuilder getValidationErrorMessage()
Return the digested data and related details for failed reference. Digests are available only if you set xml.debug.verify
Returns:

getSignatureDetails

public java.lang.StringBuilder getSignatureDetails()
Return the digested data for signature and references. Digests are available only if you set xml.debug.digest
Returns:

Skip navigation links

Oracle Fusion Middleware XML Security Java API Reference for Oracle Security Developer Tools
11g Release 1 (11.1.1)

E10680-05


Copyright © 2005, 2013 , Oracle. All rights reserved.