DSIGReference Class Reference
[Main Signature API]

#include <DSIGReference.hpp>

Collaboration diagram for DSIGReference:

[legend]List of all members.

---

Detailed Description

The class used for manipulating Reference Elements within a signature.

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

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

---

Constructor & Destructor Documentation

DSIGReference::DSIGReference (  const XSECEnv *  env, XERCES_CPP_NAMESPACE_QUALIFIER 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: env  The operating environment in which the Reference is operating dom  The DOM node (within doc) that is to be used as the base of the reference. See also: load DSIGSignature::createReference

DSIGReference::DSIGReference (  const XSECEnv *  env  )

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: env  The environment object for this reference. See also: load DSIGSignature::createReference

DSIGReference::~DSIGReference (   )

Destructor. Note: Does not impact any created DOM structures when destroyed. 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.

DSIGTransformXPathFilter* DSIGReference::appendXPathFilterTransform (  void   )

Append an XPath-Filter2 Transform to the Reference. The returned DSIGTransformXPathFilter will have no actual filter expressions loaded, but calls can be made to DSIGTransformXPathFilter::appendTransform to add them. Returns: The newly created XPath Filter transform

DSIGTransformXPath* DSIGReference::appendXPathTransform (  const 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 (  XERCES_CPP_NAMESPACE_QUALIFIER 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.

XERCES_CPP_NAMESPACE_QUALIFIER DOMElement* DSIGReference::createBlankReference (  const XMLCh *  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. Set to NULL for an anonymous reference. hm  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.

static TXFMChain* 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.

hashMethod DSIGReference::getHashMethod (  void   )  [inline]

Get the Digest method. Obtain the digest method used to find a hash for this reference Returns: the hashMethod

DSIGReferenceList* DSIGReference::getManifestReferenceList (   )

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

DSIGTransformList* DSIGReference::getTransforms (  void   )  [inline]

Obtain the transforms for this reference. Get the DSIGTransformList object for this reference. Can be used to obtain information about the transforms and also change the the transforms

const XMLCh* DSIGReference::getURI (   )

Return the URI string of the Reference. Returns: A pointer to the buffer (owned by the Reference) containing the value of the URI stored inthe reference

static TXFMBase* DSIGReference::getURIBaseTXFM (  XERCES_CPP_NAMESPACE_QUALIFIER DOMDocument *  doc, const XMLCh *  URI, const XSECEnv *  env )  [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 env  The environment the signature is operating in Returns: A base TXFM element.

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

static DSIGReferenceList* DSIGReference::loadReferenceListFromXML (  const XSECEnv *  env, XERCES_CPP_NAMESPACE_QUALIFIER 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: env  The environment in which this reference resides firstReference  First reference in DOM structure Returns: the created list.

static DSIGTransformList* DSIGReference::loadTransforms (  XERCES_CPP_NAMESPACE_QUALIFIER DOMNode *  transformsNode, XSECSafeBufferFormatter *  formatter, const XSECEnv *  env )  [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 env  Environment in which to operate 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.

static 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

---