---

DSIGReference Class Reference
[Main Signature API]

The class used for manipulating Reference Elements within a signature. More...

#include <DSIGReference.hpp>

Collaboration diagram for DSIGReference:

[legend]List of all members.

Public Methods
Constructors and Destructors
	DSIGReference (DSIGSignature *sig, DOMNode *dom)
	Contructor for use with existing XML signatures or templates. More...
	DSIGReference (DSIGSignature *sig)
	Contructor for use when creating new Reference structures. More...
	~DSIGReference ()
	Destructor. More...
Reference Construction and Manipulation
void	load ()
	Load a DSIGReference from an existing DOM structure. More...
DOMElement *	createBlankReference (char *URI, hashMethod hm, char *type)
	Create a Reference structure in the document. More...
DSIGTransformEnvelope *	appendEnvelopedSignatureTransform ()
	Append an Enveloped Signature Transform to the Reference. More...
DSIGTransformBase64 *	appendBase64Transform ()
	Append a Base64 Transform to the Reference. More...
DSIGTransformXPath *	appendXPathTransform (char *expr)
	Append an XPath Transform to the Reference. More...
DSIGTransformXSL *	appendXSLTransform (DOMNode *stylesheet)
	Append an XSLT Transform to the Reference. More...
DSIGTransformC14n *	appendCanonicalizationTransform (canonicalizationMethod cm)
	Append a Canonicalization Transform to the Reference. More...
void	setPreHashTXFM (TXFMBase *t)
	Append a "debug" transformer. More...
Getting Information
XSECBinTXFMInputStream *	makeBinInputStream (void) const
	Create an input stream based on the digested byte stream. More...
const safeBuffer &	getURISB ()
	Return the URI string of the Reference. More...
bool	isManifest ()
	Determine whether the reference is a manifest. More...
DSIGReferenceList *	getManifestReferenceList ()
	Get the Manifest. More...
Message Digest/Hash manipulation
unsigned int	calculateHash (XMLByte *toFill, unsigned int maxToFill)
	Calculate the Hash value of a reference. More...
unsigned int	readHash (XMLByte *toFill, unsigned int maxToFill)
	Read the hash from the Reference element. More...
bool	checkHash ()
	Validate the Reference element. More...
void	setHash ()
	Set the value of the hash in the Reference. More...
Static Public Methods
Helper (static) Functions
TXFMBase *	DSIGReference::createTXFMChainFromList (TXFMBase *input, DSIGTransformList *lst)
	Create a Transformer chain. More...
DSIGTransformList *	loadTransforms (DOMNode *transformsNode, XSECSafeBufferFormatter *formatter, DSIGSignature *sig)
	Load a Transforms list from the <Transforms> DOMNode. More...
TXFMBase *	getURIBaseTXFM (DOMDocument *doc, safeBuffer URI, XSECURIResolver *resolver)
	Create a starting point for a TXFM Chain. More...
DSIGReferenceList *	loadReferenceListFromXML (DSIGSignature *sig, DOMNode *firstReference)
	Load a series of references. More...
bool	verifyReferenceList (DSIGReferenceList *lst, safeBuffer &errorStr)
	Validate a list of references. More...
void	hashReferenceList (DSIGReferenceList *list, bool interlocking=true)
	Hash a reference list. More...

---

Detailed Description

The class used for manipulating Reference Elements within a signature.

The DSIGReference class creates and manipulates (including hashing and validating) <Reference> elements.

---

Constructor & Destructor Documentation

DSIGReference::DSIGReference (  DSIGSignature *    sig, DOMNode *    dom )

Contructor for use with existing XML signatures or templates. Create a DSIGReference object based on an already existing DSIG Reference XML node. It is assumed that the underlying DOM structure is in place and works correctly. Note: DSIGReference structures should only ever be created via calls to a DSIGSignature object. Parameters: doc  The DOM document node in which the signature is embedded. dom  The DOM node (within doc) that is to be used as the base of the reference. See also: load , DSIGSignature::createReference

DSIGReference::DSIGReference (  DSIGSignature *    sig )

Contructor for use when creating new Reference structures. Create a DSIGReference object that can later be used to create a new Reference structure in the DOM document. Note: DSIGReference structures should only ever be created via calls to a DSIGSignature object. Parameters: doc  The DOM document node in which the signature is embedded. See also: load , DSIGSignature::createReference

DSIGReference::~DSIGReference (    )

Destructor. Note: Does not impact any created DOM structures when destroyed. Note: DSIGReferences should never be destroyed/deleted by applications. They are owned and managed by DSIGSignature structures.

---

Member Function Documentation

DSIGTransformBase64* DSIGReference::appendBase64Transform (    )

Append a Base64 Transform to the Reference. Returns: The newly created Base64 transform.

DSIGTransformC14n* DSIGReference::appendCanonicalizationTransform (  canonicalizationMethod    cm )

Append a Canonicalization Transform to the Reference. Parameters: cm  The type of canonicalisation to be added. Returns: The newly create canonicalisation transform

DSIGTransformEnvelope* DSIGReference::appendEnvelopedSignatureTransform (    )

Append an Enveloped Signature Transform to the Reference. Appends a simple enveloped-signature transform to the list of transforms in this element. Returns: The newly created envelope transform.

DSIGTransformXPath* DSIGReference::appendXPathTransform (  char *    expr )

Append an XPath Transform to the Reference. Append an XPath transform. Namespaces can be added to the transform directly using the returned DSIGTransformXPath structure Parameters: expr  The XPath expression to be placed in the transform. Returns: The newly created XPath transform

DSIGTransformXSL* DSIGReference::appendXSLTransform (  DOMNode *    stylesheet )

Append an XSLT Transform to the Reference. The caller must have already create the stylesheet and turned it into a DOM structure that is passed in as the stylesheet parameter. Parameters: stylesheet  The stylesheet DOM structure to be placed in the reference. Returns: The newly create XSLT transform

unsigned int DSIGReference::calculateHash (  XMLByte *    toFill, unsigned int    maxToFill )

Calculate the Hash value of a reference. Takes the Reference URI, performs all the transforms and finally calculates the Hash value of the data using the Digest algorithm indicated in the reference Parameters: toFill  A Buffer that the raw hash will be copied into. maxToFill  Maximum number of bytes to place in the buffer Returns: The number of bytes copied into the buffer

bool DSIGReference::checkHash (    )

Validate the Reference element. Performs a calculateHash() and a @readHash() and then compares the results. Returns: true iff the hash of the data matches the hash stored in the reference.

DOMElement* DSIGReference::createBlankReference (  char *    URI, hashMethod    hm, char *    type )

Create a Reference structure in the document. This function will create a Reference structure in the owner document. In some cases, a call to this function will be sufficient to put the required Reference in place. In other cases, calls will also need to be made to the various append*Transform methods. Note: The XSEC Library currently makes very little use of type attributes in <Reference> Elements. However this may of use to calling applications. Parameters: URI  The URI (data source) for this reference. hashMethod  The type of Digest to be used (generally SHA-1) type  A type string (as defined by XML Signature). Returns: The root Reference element of the newly created DOM structure.

TXFMBase* DSIGReference::DSIGReference::createTXFMChainFromList (  TXFMBase *    input, DSIGTransformList *    lst )  [static]

Create a Transformer chain. Given a TransformList create the corresponding TXFM chain to allow the caller to read the reference byte stream Note: This method is primarily for use within the XSEC library. Users wishing to get the byte stream should use the makeBinInputStream method instead. Parameters: input  The input transformer to which the TXFMs will be applied to This is generally created from the URI attribute of the reference. lst  The list of Transform elements from which to build the transformer list. Returns: The end of the newly build TXFM chain. This can be read from using TXFMBase::readBytes() to give the end result of the transforms.

DSIGReferenceList* DSIGReference::getManifestReferenceList (    )

Get the Manifest. Returns: The ReferenceList containing the references in the Manifest list of this reference element.

TXFMBase* DSIGReference::getURIBaseTXFM (  DOMDocument *    doc, safeBuffer    URI, XSECURIResolver *    resolver )  [static]

Create a starting point for a TXFM Chain. Uses the provided URI to find the base data that the Transformer chain will be built upon. Parameters: doc  The document that the signature is based on (used for local URIs) URI  The URI to build the base from resolver  The (user provided) resolver that is used to translate the URI into a byte stream (for non relative URIs). Returns: A base TXFM element.

const safeBuffer& DSIGReference::getURISB (    )

Return the URI string of the Reference. Returns: A safeBuffer containing the value of the URI stored in the reference

void DSIGReference::hashReferenceList (  DSIGReferenceList *    list, bool    interlocking = true )  [static]

Hash a reference list. Run through a list of references and calculate the hash value of each element. Finally set the Base64 encoded string according to the newly calcuated hash. Note: This is an internal library function and should not be called directly. Parameters: list  The list of references interlocking  If set to false, the library will assume there are no inter-related references. The algorithm for determining this internally is very primitive and CPU intensive, so this is a method to bypass the checks.

bool DSIGReference::isManifest (    )

Determine whether the reference is a manifest. Returns: true iff the Reference element is a Manifest reference

void DSIGReference::load (    )

Load a DSIGReference from an existing DOM structure. This function will load a Reference structure from the owner document.

DSIGReferenceList* DSIGReference::loadReferenceListFromXML (  DSIGSignature *    sig, DOMNode *    firstReference )  [static]

Load a series of references. Takes a series of <Reference> elements in a DOM structure and creates the corresponding ReferenceList object. Note: Internal function - meant for use by the library Parameters: sig  DSIGSignature object that will own the list firstReference  First reference in DOM structure Returns: the created list.

DSIGTransformList* DSIGReference::loadTransforms (  DOMNode *    transformsNode, XSECSafeBufferFormatter *    formatter, DSIGSignature *    sig )  [static]

Load a Transforms list from the <Transforms> DOMNode. Reads the data from the XML data stored in the DOM and create the associated DSIGTrasnformList. Parameters: transformsNode  Starting node in the DOM formatter  The formatter to be used to move from XMLCh to strings sig  The signature that will own the list Returns: A pointer to the created list.

XSECBinTXFMInputStream* DSIGReference::makeBinInputStream (  void    )  const

Create an input stream based on the digested byte stream. This method allows applications to read the fully canonicalised byte stream that is hashed for a reference. All transforms are performed up to the point where they would normally be fed into the Digest function. Returns: A BinInputSource of the canonicalised SignedInfo

unsigned int DSIGReference::readHash (  XMLByte *    toFill, unsigned int    maxToFill )

Read the hash from the Reference element. Reads the Base64 encoded element from the Reference element. The hash is then translated from Base64 back into raw form and written into the indicated buffer. Parameters: toFill  Pointer to the buffer where the raw hash will be written maxToFill  Maximum bytes to write to the buffer Returns: Number of bytes written

void DSIGReference::setHash (    )

Set the value of the hash in the Reference. Hashes the data referenced by the element and then writes the Base64 encoded hash value into the Reference.

void DSIGReference::setPreHashTXFM (  TXFMBase *    t )

Append a "debug" transformer. This method allows applications to provide a TXFM that will be appended to the transform chain just prior to the application of the hash algorithm. Note: This is primarily for debugging. It should not be used to modify the contents of the byte stream. Parameters: t  The TXFM element to insert.

bool DSIGReference::verifyReferenceList (  DSIGReferenceList *    lst, safeBuffer &    errorStr )  [static]

Validate a list of references. Runs through a reference list, calling verify() on each and setting the ErrroStrings for any errors found Parameters: lst  The list to verify errorStr  The string to append any errors found to Returns: true iff all the references validate successfully.

---

The documentation for this class was generated from the following file:

• DSIGReference.hpp

---