com.rsa.certj.xml.dsig

Class Reference

java.lang.Object
  |
  +--com.rsa.certj.xml.dsig.Reference

All Implemented Interfaces:

Cloneable, Serializable

public class Reference

extends Object

implements Cloneable, Serializable

This class creates and stores the Reference element in an XML signature. It includes the digest method and resulting digest value calculated over the identified data object. It also may include transformations that produce the input to the digest operation. Reference validation involves the checking of the digest value against the identified data object.

Copyright © RSA Security Inc., 2001-2002. All rights reserved.

See Also

Serialized Form

Field Summary

static String	MANIFEST_TYPE Specifies that the URI of this reference contains a Manifest element.
static String	OBJECT_TYPE Specifies that the URI of this reference contains an Object element.
static String	REFERENCE_TYPE Specifies that the URI of this reference contains a Reference element.
static String	SIGNATURE_PROPERTY_TYPE Specifies that the URI of this reference contains a SignatureProperties (this includes assertions about the signature itself, such as the time of signing or the serial number of hardware used in cryptographic processes).

Constructor Summary

Reference()

Creates an empty Reference object without initializing any attributes.

Reference(String uri)

Creates a Reference object and sets the URI setting to uri.

Reference(String uri, String digestMethod, Transformer[] transforms)

Creates a Reference object and sets the attributes to the given values.

Reference(String uri, String digestMethod, Transformer[] transforms, String referenceType)

Creates a Reference object and initializes it with the given values.

Reference(String uri, String digestMethod, Transformer[] transforms, String referenceType, Manifest manifest)

Creates a Reference object with the given values.

Method Summary

void	addTransform(Transformer transform) Adds a transformation to this reference object by appending the Transformer object in transform to the existing transformations.
org.w3c.dom.Element	generateReferenceElement(XMLSignature xmlSignature, org.w3c.dom.Document document) Generates the Reference element with its attribute values.
String	getDigestMethod() Gets the digest algorithm of this reference.
byte[]	getDigestValue() Gets the digest value.
Manifest	getManifest() Returns the manifest as a Manifest object.
String	getReferenceID() Returns the ID of the Reference as a String object.
String	getReferenceType() Returns the reference type.
Transformer	getTransform(int index) Gets the transformer located at index.
int	getTransformCount() Gets the number of Tranformer objects in this reference.
Transformer[]	getTransforms() Gets the ordered transformation list of this reference.
String	getURI() Returns the URI of this reference.
void	parseReference(org.w3c.dom.Element referenceNode, String xmlNamespace) This method retrieves the data from the passed in reference node, and sets all the attributes of this Reference.
static org.w3c.dom.Element	resolveId(org.w3c.dom.Node inputNode, String id) Finds the element from the inputNode, the element should contain an attribute with value of id.
void	setDigestMethod(String digestMethod) Sets the digest algorithm of this reference.
void	setManifest(Manifest manifest) Sets the Manifest of this Reference instance as the passed-in value.
void	setReferenceID(String id) Sets the ID of this Reference to id.
void	setReferenceType(String type) Sets the reference type.
void	setTransform(Transformer[] transforms) Sets the tranformation list to this Reference object by overriding the existing ones.
void	setURI(String uri) Sets the URI of this reference to the given value.
boolean	verify(XMLSignature signature, StringBuffer description) Validates references by performing transformations on the identified data object, digesting the resulting data object by using digestMethod, and then comparing the generated digest value against the digest value in the reference.
boolean	verifyManifest(XMLSignature xmlSignature, StringBuffer[] descriptions) Validates each Reference element in the manifest of the current Reference instance.

Methods inherited from class java.lang.Object

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

Field Detail

SIGNATURE_PROPERTY_TYPE

public static final String SIGNATURE_PROPERTY_TYPE

Specifies that the URI of this reference contains a SignatureProperties (this includes assertions about the signature itself, such as the time of signing or the serial number of hardware used in cryptographic processes).

MANIFEST_TYPE

public static final String MANIFEST_TYPE

Specifies that the URI of this reference contains a Manifest element.

OBJECT_TYPE

public static final String OBJECT_TYPE

Specifies that the URI of this reference contains an Object element.

REFERENCE_TYPE

public static final String REFERENCE_TYPE

Specifies that the URI of this reference contains a Reference element.

Constructor Detail

Reference

public Reference()

Creates an empty Reference object without initializing any attributes. This is the default constructor.

Reference

public Reference(String uri)

Creates a Reference object and sets the URI setting to uri.

Parameters

uri

A String containing the URI that identifies the data object.

Reference

public Reference(String uri,
                 String digestMethod,
                 Transformer[] transforms)

Creates a Reference object and sets the attributes to the given values.

Parameters

	uri		The URI that identifies the data object.
	digestMethod		The digest algorithm.
	transforms		The list of transformations to perform on the data object.

Reference

public Reference(String uri,
                 String digestMethod,
                 Transformer[] transforms,
                 String referenceType)

Creates a Reference object and initializes it with the given values.

Parameters

	uri		The URI that identifies the data object.
	digestMethod		The digest algorithm name.
	transforms		The list of transformations to be performed on the data object.
	referenceType		An optional String value provides information about the resource identified by the URI, whether it is an Object, SignatureProperty, or Manifest. Possible values are OBJECT_TYPE, SIGNATURE_PROPERTY_TYPE, and MANIFEST_TYPE. If no value is passed, the default is OBJECT_TYPE.

Reference

public Reference(String uri,
                 String digestMethod,
                 Transformer[] transforms,
                 String referenceType,
                 Manifest manifest)

Creates a Reference object with the given values.

Parameters

	uri		The URI that identifies the data object.
	digestMethod		The digest algorithm name.
	transforms		The list of transformations to be performed on the data object.
	referenceType		An optional String value provides information about the resource identified by the URI, whether it is an Object, SignatureProperty, or Manifest. Possible values are OBJECT_TYPE, SIGNATURE_PROPERTY_TYPE, and MANIFEST_TYPE. In this constructor, the value should be MANIFEST_TYPE, because a Manifest object is passed in the parameter manifest.
	manifest		A Manifest object that belongs to this Reference instance.

Method Detail

setReferenceType

public void setReferenceType(String type)

Sets the reference type.

Parameters

type

A String value containing the resource type identified by the URI. Possible values are OBJECT_TYPE, SIGNATURE_PROPERTY_TYPE, and MANIFEST_TYPE.

getReferenceType

public String getReferenceType()

Returns the reference type.

Returns

The resource type identified by the URI. The returned String can be one of the following: OBJECT_TYPE, SIGNATURE_PROPERTY_TYPE, or MANIFEST_TYPE.

setURI

public void setURI(String uri)

Sets the URI of this reference to the given value.

Parameters

uri

A String value that identifies the input data.

getURI

public String getURI()

Returns the URI of this reference.

Returns

The URI String of this Reference.

addTransform

public void addTransform(Transformer transform)

Adds a transformation to this reference object by appending the Transformer object in transform to the existing transformations.

Transformations describe how the signer obtained the data object that was digested. This argument is optional. There can be any number of transforms. The output of each transform (octets) serves as input to the next transform. The input for the first transform is the source data. The output from the last transform is the input for the digest algorithm. Each transform consists of an algorithm attribute (the name of the algorithm to perform), optional MimeType and CharSet attributes, and content parameters, if any, appropriate for the given algorithm. Examples of transforms include Base 64 decoding, canonicalization, and XPath filtering.

Note: The order of tranformers in the transformation list is critical. If the tranformation list contains EnvelopedTransformer, it should be before C14NTransformer and Base64Transformer, because it requires the original node-set pointed to by the URI as its input. Otherwise, the reference digest value will not be generated correctly.

Parameters

transform

A Transformer object to add.

setTransform

public void setTransform(Transformer[] transforms)

Sets the tranformation list to this Reference object by overriding the existing ones.

Note: The order of tranformers in the transformation list is critical. If the tranformation list contains EnvelopedTransformer, it should be before C14NTransformer and Base64Transformer, because it requires the original node-set pointed to by the URI as its input. Otherwise, the reference digest value will not be generated correctly.

Parameters

transforms

The list of transformations as a Transformer object array.

getTransform

public Transformer getTransform(int index)

Gets the transformer located at index.

Parameters

index

The position of the transform in the transform list.

Returns

The Transformer object at the specified position, or null if the index is invalid.

getTransformCount

public int getTransformCount()

Gets the number of Tranformer objects in this reference.

Returns

An integer containing the number of Transformer objects in this reference.

getTransforms

public Transformer[] getTransforms()

Gets the ordered transformation list of this reference.

Returns

The ordered Transformer object list.

setDigestMethod

public void setDigestMethod(String digestMethod)

Sets the digest algorithm of this reference.

Parameters

digestMethod

The digest algorithm to apply to the signed object. Call this method only when signing the document.

getDigestMethod

public String getDigestMethod()

Gets the digest algorithm of this reference.

Returns

The digest algorithm as a String.

getDigestValue

public byte[] getDigestValue()

Gets the digest value.

Returns

The digest value as a byte array.

getReferenceID

public String getReferenceID()

Returns the ID of the Reference as a String object.

Returns

The ID of this Reference as a String object.

setReferenceID

public void setReferenceID(String id)

Sets the ID of this Reference to id.

Parameters

id

A String object containing the ID of this Reference object.

setManifest

public void setManifest(Manifest manifest)

Sets the Manifest of this Reference instance as the passed-in value.

Parameters

manifest

A Manifest object that will be assigned as the manifest of this Reference instance.

getManifest

public Manifest getManifest()

Returns the manifest as a Manifest object.

Returns

The manifest as a Manifest object.

parseReference

public void parseReference(org.w3c.dom.Element referenceNode,
                           String xmlNamespace)
                    throws XMLException

This method retrieves the data from the passed in reference node, and sets all the attributes of this Reference.

Internal method, do not use

Parameters

referenceNode

a DOM Element contains all the information of this reference

Throws

XMLException - If there is error occured during parsing the Reference node.

generateReferenceElement

public org.w3c.dom.Element generateReferenceElement(XMLSignature xmlSignature,
                                                    org.w3c.dom.Document document)
                                             throws XMLException

Generates the Reference element with its attribute values.

Internal method, do not use

Parameters

	xmlSignature		the XMLSignature object contains this reference
	document		the Document object that should be the root of the generated Reference element

Returns

a DOM Element object storing the data of this Reference object

Throws

XMLException - If there is an error ocurred during generating the Reference element.

verifyManifest

public boolean verifyManifest(XMLSignature xmlSignature,
                              StringBuffer[] descriptions)
                       throws XMLException

Validates each Reference element in the manifest of the current Reference instance. It returns true if all the reference validations succeed. It returns false if any reference validations fail.

This method should be called only when this Reference object is a Manifest type. If it is not a Manifest type, this method always returns true.

Parameters

	xmlSignature		An XMLSignature object containing the current Reference instance.
	descriptions		A StringBuffer array used to store the descriptions of each reference validation result. If any of the StringBuffer object descriptions are null, no description is provided for reference at that position.

Returns

true if each reference validation succeeds; false, otherwise.

Throws

XMLException - If an error occured while verifying the manifest.

verify

public boolean verify(XMLSignature signature,
                      StringBuffer description)
               throws XMLException

Validates references by performing transformations on the identified data object, digesting the resulting data object by using digestMethod, and then comparing the generated digest value against the digest value in the reference.

Parameters

	signature		An XMLSignature object that contains this reference object. It is used to obtain the data object to be digested.
	description		A String describing the cause of the reference verification failure. If it is null, then no description is provided.

Returns

true if the validation is successful; false if there is any mismatch.

Throws

XMLException - If an error occurs during reference validation. For example, this method throws an exception if the XMLSignature object that contains this reference is not available.

resolveId

public static org.w3c.dom.Element resolveId(org.w3c.dom.Node inputNode,
                                            String id)
                                     throws XMLException

Finds the element from the inputNode, the element should contain an attribute with value of id.

Internal method, do not use

Parameters

	inputNode		a Node object specifies where to look at.
	id		the string value of the attribute node with node name "ID" or "id" or "Id".

Returns

the element containing an attribute ID/id/Id with the value equals to the passed in id

Throws

XMLException - If there is an error occured during searching the the element.