oracle.security.xmlsec.dsig

Class XSReference

java.lang.Object

oracle.security.xmlsec.util.XMLNode

oracle.security.xmlsec.util.XMLElement

oracle.security.xmlsec.dsig.ObjectReference

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:

• Any URL using a protocol scheme for which the appropriate java.net.URLStreamHandlerFactory is installed.
• Same-document URIs of the form "" and "#foo".
• Same-document XPointers of the form "#xpointer(/)" and "#xpointer(id('foo'))".

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:

• SHA-1 XMLURI.alg_sha1
• SHA-256 XMLURI.alg_sha256
• SHA-384 XMLURI.alg_sha384
• SHA-512 XMLURI.alg_sha512
• MD5 XMLURI.alg_md5

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:

• XML Signature:
  • ManifestXMLURI.obj_Manifest
  • Object container XMLURI.obj_Object
  • Signature Properties XMLURI.obj_SignatureProperties
• XML Encryption:
  • Encryption Properties XMLURI.obj_EncryptionProperties
• KeyInfo Types:
  • Diffie-Hellman Public Key XMLURI.obj_DHKeyValue
  • DSA Public Key XMLURI.obj_DSAKeyValue
  • Encrypted Key XMLURI.obj_EncryptedKey
  • Key Name XMLURI.obj_KeyName
  • Key Management Data XMLURI.obj_MgmtData
  • PGP Key Data XMLURI.obj_PGPData
  • Raw (base-64 encoded binary) X.509 Certificate XMLURI.obj_rawX509Certificate
  • Key Retrieval Method XMLURI.obj_RetrievalMethod
  • RSA Public Key XMLURI.obj_RSAKeyValue
  • SPKI Key Data XMLURI.obj_SPKIData
  • X.509 Key/Certificate Data XMLURI.obj_X509Data

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

Constructors

Constructor and Description
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

Modifier and Type	Method and Description
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,
                          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:

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,
                          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:

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,
                          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:

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,
                          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:

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,
                          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:

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,
                          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:

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: