Overview | Package | Class | Tree | Deprecated | Index | Help
| Oracle Security Developer Tools XML Security Java API Reference 10g Release 3 (10.1.3) B25383-01
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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:
  - Manifest`XMLURI.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()`

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.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 dereferenced data object (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.
`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.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, getTransforms, getURI, setURI`

Methods inherited from class oracle.security.xmlsec.util.XMLElement
`addNSPrefixAttr, addNSPrefixAttr, addNSPrefixAttrDefault, addNSPrefixAttrDefault, getAttribute, getAttributeNode, getAttributeNodeNS, getAttributeNS, getChildElementsByTagName, getChildElementsByTagName, getChildElementsByTagNameNS, getChildElementsByTagNameNS, getDefaultNSPrefix, 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.

### 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.
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`.

### 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.

### 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.

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(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

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

### getDigestedData

    public byte[] getDigestedData()

  Returns the dereferenced data object (after any Transforms have been applied) that was obtained as a result of calling one of the `computeDigest` or `validate` methods.
  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)`

Overview | Package | Class | Tree | Deprecated | Index | Help
| Oracle Security Developer Tools XML Security Java API Reference 10g Release 3 (10.1.3) B25383-01
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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