DSIGSignature Class Reference
[Main Signature API]

#include <DSIGSignature.hpp>

Collaboration diagram for DSIGSignature:

[legend]List of all members.

---

Detailed Description

The main class used for manipulating XML Digital Signatures.

The DSIGSignature class is used to manipulate and verify <signature> blocks. It should only ever be created via the XSECProvider class.

Public Member Functions
Load and Setup Functions
void	load (void)
	Load the signature information from the DOM source.
void	setSigningKey (XSECCryptoKey *k)
	Externally set the signing/verification key.
Signature Operations
bool	verify (void)
	Verify that a signature is valid.
bool	verifySignatureOnly (void)
	Verify a signature is valid (skip references).
void	sign (void)
	Sign a DSIGSignature DOM structure.
Functions to create and manipulate signature elements.
void	setDSIGNSPrefix (const XMLCh *prefix)
	Set the prefix be used for the DSIG namespace.
void	setECNSPrefix (const XMLCh *prefix)
	Set the prefix be used for the Exclusive Canonicalisation namespace.
void	setXPFNSPrefix (const XMLCh *prefix)
	Set the prefix be used for the XPath-Filter2 namespace.
void	setPrettyPrint (bool flag)
	Set Pretty Print.
bool	getPrettyPrint (void)
	Tell caller whether PrettyPrinting is active.
XERCES_CPP_NAMESPACE_QUALIFIER DOMElement *	createBlankSignature (XERCES_CPP_NAMESPACE_QUALIFIER DOMDocument *doc, canonicalizationMethod cm=CANON_C14N_NOC, signatureMethod sm=SIGNATURE_DSA, hashMethod hm=HASH_SHA1)
	Create a <Signature> DOM structure.
DSIGReference *	createReference (const XMLCh *URI, hashMethod hm=HASH_SHA1, char *type=NULL)
	Add a new reference to the end of the list of <Reference> nodes.
General and Information functions.
unsigned int	calculateSignedInfoAndReferenceHash (unsigned char *hashBuf, unsigned int hashBufLen)
	Get the hash of the Signed Value.
unsigned int	calculateSignedInfoHash (unsigned char *hashBuf, unsigned int hashBufLen)
	Get the hash of the Signed Value.
DSIGReferenceList *	getReferenceList (void)
	Return the reference list for outside use.
XSECBinTXFMInputStream *	makeBinInputStream (void) const
	Create an input stream from SignedInfo.
const XMLCh *	getErrMsgs (void)
	Get the Error messages from the last verify.
const XMLCh *	getDSIGNSPrefix ()
	Get the NS Prefix being used for DSIG elements.
const XMLCh *	getECNSPrefix ()
	Get the NS being used for EC nodes.
const XMLCh *	getXPFNSPrefix ()
	Get the NS being used for XPath Filter2 nodes.
XERCES_CPP_NAMESPACE_QUALIFIER DOMDocument *	getParentDocument ()
canonicalizationMethod	getCanonicalizationMethod (void)
	Get canonicalisation algorithm.
hashMethod	getHashMethod (void)
	Get the hash method.
signatureMethod	getSignatureMethod (void)
	Get the signature method.
const XMLCh *	getSignatureValue (void) const
	Get the Signature Value.
XSECSafeBufferFormatter *	getSBFormatter (void)
	Helper function for sub Classes.
Resolver manipulation
void	setURIResolver (XSECURIResolver *resolver)
	Register a URIResolver.
XSECURIResolver *	getURIResolver (void)
	Return a pointer to the resolver being used.
void	setKeyInfoResolver (XSECKeyInfoResolver *resolver)
	Register a KeyInfoResolver.
XSECKeyInfoResolver *	getKeyInfoResolver (void)
	Return a pointer to the resolver being used.
KeyInfo Element Manipulation
DSIGKeyInfoList *	getKeyInfoList ()
	Get the list of <KeyInfo> elements.
void	clearKeyInfo (void)
	Clear out all KeyInfo elements in the signature.
DSIGKeyInfoValue *	appendDSAKeyValue (const XMLCh *P, const XMLCh *Q, const XMLCh *G, const XMLCh *Y)
	Append a DSA KeyValue element.
DSIGKeyInfoValue *	appendRSAKeyValue (const XMLCh *modulus, const XMLCh *exponent)
	Append a RSA KeyValue element.
DSIGKeyInfoX509 *	appendX509Data (void)
	Append a X509Data element.
DSIGKeyInfoName *	appendKeyName (const XMLCh *name, bool isDName=false)
	Append a KeyName element.
DSIGKeyInfoPGPData *	appendPGPData (const XMLCh *id, const XMLCh *packet)
	Append a PGPData element.
DSIGKeyInfoSPKIData *	appendSPKIData (const XMLCh *sexp)
	Append a SPKIData element.
DSIGKeyInfoMgmtData *	appendMgmtData (const XMLCh *data)
	Append a MgmtData element.
Object handling
DSIGObject *	appendObject (void)
	Append an object container.
int	getObjectLength (void)
	Find the number of ds:Object nodes within the Signature.
DSIGObject *	getObjectItem (int i)
	Get a particular ds:Object from within the Signature.
ID handling
void	setIdByAttributeName (bool flag)
	Set Id finding behaviour.
bool	getIdByAttributeName (void)
	Determine Id finding behaviour.
void	registerIdAttributeName (const XMLCh *name)
	Add an attribute name to be searched for when looking for Id attributes.
bool	deregisterIdAttributeName (const XMLCh *name)
	Remove an attribute name to be searched for when looking for Id attributes.
void	registerIdAttributeNameNS (const XMLCh *ns, const XMLCh *name)
	Add an attribute name within a particular Namespace to be searched for when looking for Id attributes.
bool	deregisterIdAttributeNameNS (const XMLCh *ns, const XMLCh *name)
	Remove an attribute name and ns to be searched for when looking for Id attributes.
Protected Member Functions
Constructors and Destructors
	DSIGSignature (XERCES_CPP_NAMESPACE_QUALIFIER DOMDocument *doc, XERCES_CPP_NAMESPACE_QUALIFIER DOMNode *sigNode)
	Contructor for use with existing XML signatures or templates.
	~DSIGSignature ()
Friends
class	XSECProvider

---

Constructor & Destructor Documentation

DSIGSignature::DSIGSignature (  XERCES_CPP_NAMESPACE_QUALIFIER DOMDocument *  doc, XERCES_CPP_NAMESPACE_QUALIFIER DOMNode *  sigNode )  [protected]

Contructor for use with existing XML signatures or templates. Create a DSIGSignature object based on an already existing DSIG Signature XML node. It is assumed that the underlying DOM structure is in place and works correctly. It is required that the caller pass in the signature DOM Node as there may be more than one signature in a document. The caller needs to specify which signature tree is to be used. Parameters: doc  The DOM document node in which the signature is embedded. sigNode  The DOM node (within doc) that is to be used as the base of the signature. See also: load

DSIGSignature::~DSIGSignature (   )  [protected]

---

Member Function Documentation

DSIGKeyInfoValue* DSIGSignature::appendDSAKeyValue (  const XMLCh *  P, const XMLCh *  Q, const XMLCh *  G, const XMLCh *  Y )

Append a DSA KeyValue element. Add a new KeyInfo element for a DSA Value Parameters: P  Base64 encoded value of P Q  Base64 encoded value of Q G  Base64 encoded value of G Y  Base64 encoded value of Y Returns: A pointer to the created object.

DSIGKeyInfoName* DSIGSignature::appendKeyName (  const XMLCh *  name, bool  isDName = false )

Append a KeyName element. Add a new KeyInfo element for a key name. Parameters: name  The name of the key to set in the XML isDName  Treat the name as a Distinguished name and encode accordingly Returns: A pointer to the created object

DSIGKeyInfoMgmtData* DSIGSignature::appendMgmtData (  const XMLCh *  data  )

Append a MgmtData element. Add a new KeyInfo element for Management Data Parameters: data  The string to set in the MgmtData element Returns: A pointer to the created object

DSIGObject* DSIGSignature::appendObject (  void   )

Append an object container. Create a new Object (i.e. a Signature <Object> which is a container element used to hold information that needs to be signed within the signature - i.e. in enveloping mode Returns: the newly created DSIGObject

DSIGKeyInfoPGPData* DSIGSignature::appendPGPData (  const XMLCh *  id, const XMLCh *  packet )

Append a PGPData element. Add a new KeyInfo element for a PGP key. Parameters: id  The ID of the key to set in the XML (base64 encoded - NULL if none) packet  The Packet information to set in the XML (base64 encoded - NULL if none) Returns: A pointer to the created object

DSIGKeyInfoValue* DSIGSignature::appendRSAKeyValue (  const XMLCh *  modulus, const XMLCh *  exponent )

Append a RSA KeyValue element. Add a new KeyInfo element for a RSA Value Parameters: modulus  Base64 encoded value of the modulus exponent  Base64 encoded value of exponent Returns: A pointer to the created object.

DSIGKeyInfoSPKIData* DSIGSignature::appendSPKIData (  const XMLCh *  sexp  )

Append a SPKIData element. Add a new KeyInfo element for a set of SPKI S-expressions Parameters: sexp  The initial S-expression to set in the SPKIData element Returns: A pointer to the created object

DSIGKeyInfoX509* DSIGSignature::appendX509Data (  void   )

Append a X509Data element. Add a new KeyInfo element for X509 data. Note: The added element is empty. The caller must make use of the returned object to set the required values. Returns: A pointer to the created object.

unsigned int DSIGSignature::calculateSignedInfoAndReferenceHash (  unsigned char *  hashBuf, unsigned int  hashBufLen )

Get the hash of the Signed Value. Function to calculate and return the hash of the <SignedInfo> structures (after the canonicalization defined by <CanonicalizationMethod> and the reference hashes have been performed). Parameters: hashBuf  Buffer to place the raw hash in. hashBufLen  The length of the buffer Returns: The length of the hash that was placed in hashBuf

unsigned int DSIGSignature::calculateSignedInfoHash (  unsigned char *  hashBuf, unsigned int  hashBufLen )

Get the hash of the Signed Value. Function to calculate and return the hash of the <SignedInfo> structures (after the canonicalization defined by <CanonicalizationMethod> has been performed). Parameters: hashBuf  Buffer to place the raw hash in. hashBufLen  The length of the buffer Returns: The length of the hash that was placed in hashBuf

void DSIGSignature::clearKeyInfo (  void   )

Clear out all KeyInfo elements in the signature. This function will delete all KeyInfo elements from both the DSIGSignature object and the associated DOM.

XERCES_CPP_NAMESPACE_QUALIFIER DOMElement* DSIGSignature::createBlankSignature (  XERCES_CPP_NAMESPACE_QUALIFIER DOMDocument *  doc, canonicalizationMethod  cm = CANON_C14N_NOC, signatureMethod  sm = SIGNATURE_DSA, hashMethod  hm = HASH_SHA1 )

Create a <Signature> DOM structure. The DOM structure created is still divorced from the document. The callee needs to take the returned <Signature> Element node and insert it at the appropriate place in their document. The signature is a skeleton only. There are no references or KeyInfo elements inserted. However the DSIGSignature structures are set up with the new information, so once an element has been created and a signing key has been set, a call to sign will sign appropriately. Note: The digest method (hash method) set here is for the signing function only. Different hash methods can be used for reference elements. Parameters: doc  The document the Signature DOM structure will be inserted into. cm  The canonicalisation method to use. sm  The signature algorithm to be used. hm  The Digest function to be used for the actual signatures. Returns: The newly created <Signature> element that the caller should insert in the document.

DSIGReference* DSIGSignature::createReference (  const XMLCh *  URI, hashMethod  hm = HASH_SHA1, char *  type = NULL )

Add a new reference to the end of the list of <Reference> nodes. Creates a new DSIGReference, adds it to the list of references handled by the owning DSIGSignature and also creates the skeleton DOM structure into the document. Note: The XSEC Library currently makes very little use of type attributes in <Reference> Elements. However this may of use to calling applications. See also: DSIGReference Parameters: URI  The Data that this Reference node refers to. hm  The hashing (digest) method to be used for this reference type  A "type" string (as defined in XML Signature). Returns: The newly created DSIGReference element.

bool DSIGSignature::deregisterIdAttributeName (  const XMLCh *  name  )

Remove an attribute name to be searched for when looking for Id attributes. This allows a user to de-register a particular name to be used to identify Id attributes. Parameters: name  Name to remove from the list of those used to find Id attributes Returns: true if found and removed, false if was not in the list

bool DSIGSignature::deregisterIdAttributeNameNS (  const XMLCh *  ns, const XMLCh *  name )

Remove an attribute name and ns to be searched for when looking for Id attributes. This allows a user to de-register a particular name to be used to identify Id attributes. Parameters: ns  Namespace in which attribute will reside name  Name to remove from the list of those used to find Id attributes Returns: true if found and removed, false if was not in the list

canonicalizationMethod DSIGSignature::getCanonicalizationMethod (  void   )  [inline]

Get canonicalisation algorithm. Returns the canonicalisation algorithm that will be/is used to canonicalise the <SignedInfo> element prior to hash/sign Returns: The canonicalisation method

const XMLCh* DSIGSignature::getDSIGNSPrefix (   )

Get the NS Prefix being used for DSIG elements. Returns: A pointer to the buffer holding the prefix See also: setDSIGNSPrefix

const XMLCh* DSIGSignature::getECNSPrefix (   )

Get the NS being used for EC nodes. Returns: A pointer to the buffer holding the prefix See also: setECNSPrefix

const XMLCh* DSIGSignature::getErrMsgs (  void   )

Get the Error messages from the last verify. Returns a list of text error messages from the last Signature operation. Each error that occurred is in the buffer, separated by new-lines. Note: The buffer is owned by the DSIGSignature object - do not delete it Returns: A pointer to the buffer containing the error strings.

hashMethod DSIGSignature::getHashMethod (  void   )  [inline]

Get the hash method. Obtain the hash (digest) algorithm that is used to generate a hash of the canonicalised <SignedInfo> element. Returns: the Hash (digest) Method

bool DSIGSignature::getIdByAttributeName (  void   )

Determine Id finding behaviour. Allows a caller to determine whether the library is currently searching for Id attributes by name Returns: The value of the IdByAttributeName flag

DSIGKeyInfoList* DSIGSignature::getKeyInfoList (   )  [inline]

Get the list of <KeyInfo> elements. This function recovers list that contains the KeyInfo elements read in from the DOM document. This list should be used by calling applications to determine what key is appropriate for validating (or even signing) the Signature. Todo: The KeyInfo process is very primitive. An interface needs to be created to allow application developers to install an object into the Signature that the Signature can call on to translate KeyInfo lists into a Key. Returns: A pointer to the DSIGKeyInfoList object held by the DSIGSignature

XSECKeyInfoResolver* DSIGSignature::getKeyInfoResolver (  void   )

Return a pointer to the resolver being used. Returns: A pointer to the KeyInfoResolver registered in this signature

DSIGObject* DSIGSignature::getObjectItem (  int  i  )

Get a particular ds:Object from within the Signature. Returns: the ith Object from the list of ds:Object nodes in the signature. Items are ordered in tree order.

int DSIGSignature::getObjectLength (  void   )

Find the number of ds:Object nodes within the Signature. Returns: the number of ds:Object nodes held in the Signature, 0 if none

XERCES_CPP_NAMESPACE_QUALIFIER DOMDocument* DSIGSignature::getParentDocument (   )  [inline]

Get the DOM_Document that this Signature is operating within. Mainly used by the library itself. Returns: The DOM_Document node.

bool DSIGSignature::getPrettyPrint (  void   )

Tell caller whether PrettyPrinting is active. Returns: True if Pretty Printing is active, false if not

DSIGReferenceList* DSIGSignature::getReferenceList (  void   )

Return the reference list for outside use. Returns a pointer to the list of references which can then be read by the caller. Returns: The referenceList

XSECSafeBufferFormatter* DSIGSignature::getSBFormatter (  void   )  [inline]

Helper function for sub Classes. Returns the pointer to the formatter being used within the Signature

signatureMethod DSIGSignature::getSignatureMethod (  void   )  [inline]

Get the signature method. Obtain the algorithm that will be used to generate/check the signature of the canonicalised and hashed <SignedInfo> element. Returns: the Signature method

const XMLCh* DSIGSignature::getSignatureValue (  void   )  const

Get the Signature Value. Returns the base64 string holding the signature value for this signature Returns: the signature value string

XSECURIResolver* DSIGSignature::getURIResolver (  void   )

Return a pointer to the resolver being used. Returns: A pointer to the URIResolver registered in this signature

const XMLCh* DSIGSignature::getXPFNSPrefix (   )

Get the NS being used for XPath Filter2 nodes. Returns: A pointer to the buffer holding the prefix See also: setXPFNSPrefix

void DSIGSignature::load (  void   )

Load the signature information from the DOM source. Used to tell the DSIGSignature object to read from the DOM tree into local structures. Will throw various exceptions if it finds that the DOM structure is not in line with the XML Signature standard.

XSECBinTXFMInputStream* DSIGSignature::makeBinInputStream (  void   )  const

Create an input stream from SignedInfo. This method allows applications to read the fully canonicalised byte stream that is hashed and signed. 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

void DSIGSignature::registerIdAttributeName (  const XMLCh *  name  )

Add an attribute name to be searched for when looking for Id attributes. This allows a user to add an attribute name to be used to identify Id attributes when they are not set to be of Type=ID in the DOM Note: Two names are registered by default - "Id" and "id". These can be removed by calling deregisterIdAttributeName Parameters: name  Name to append to the list of those used to find Id attributes

void DSIGSignature::registerIdAttributeNameNS (  const XMLCh *  ns, const XMLCh *  name )

Add an attribute name within a particular Namespace to be searched for when looking for Id attributes. This allows a user to add an attribute name to be used to identify Id attributes when they are not set to be of Type=ID in the DOM Note: Two names are registered by default - "Id" and "id". These can be removed by calling deregisterIdAttributeName Parameters: ns  Namespace in which attribute will reside name  Name to append to the list of those used to find Id attributes

void DSIGSignature::setDSIGNSPrefix (  const XMLCh *  prefix  )

Set the prefix be used for the DSIG namespace. When the XSEC library creates XML Element nodes, it uses the prefix here for all nodes created. By default, the library assumes that the default namespace is used. The createBlankSignature function will use this prefix to setup the dsig namespace. E.g. (assuming a call has been made to set the prefix to "ds") the <Signature> element will have a namespace attribute added of xmlns:ds="http://www.w3.org/2000/09/xmldsig#" If no prefix has been set, this attribute will be set as the default namespace See also: createBlankSignature Parameters: prefix  The UTF-16 encoided NS prefix to use for the XML Digital Signature nodes

void DSIGSignature::setECNSPrefix (  const XMLCh *  prefix  )

Set the prefix be used for the Exclusive Canonicalisation namespace. The Exclusive Canonicalisation specification defines a new namespace for the InclusiveNamespaces node. This function can be used to set the prefix that the library will use when creating nodes within this namespace. xmlns:ds="http://www.w3.org/2001/10/xml-exc-c14n#" If no prefix is set, the default namespace will be used See also: createBlankSignature Parameters: prefix  The UTF-16 encoided NS prefix to use for the XML Exclusive Canonicalisation nodes

void DSIGSignature::setIdByAttributeName (  bool  flag  )

Set Id finding behaviour. The library de-references "#obj" URI references to ID attributes within a DOM document. Currently, the library first uses DOM calls to find if the Id has been properly set within the document via the parser or one of the DOM Level 3 calls to set an Id. If no Id is found of the correct name, the library then starts searching for attributes of a given name with the required value. This list defaults to "id" and "Id", but can be modified via a call to addIdAttributeName() The setIdByAttributeName call enables or disables the second part of the Id search. I.e. when the Id doesn't exist as an attribute of Type=ID, whether or not to search for an attribute of a name in the list of names. By default this behaviour is enabled. Warning: This is currently enabled by default for backwards compatibility reasons only. Future version may reverse this and ship disabled by default, as this behaviour is a potential security risk. Parameters: flag  Enable (true) or Disable (false) searching for Id attributes by name

void DSIGSignature::setKeyInfoResolver (  XSECKeyInfoResolver *  resolver  )

Register a KeyInfoResolver. Registers a KeyInfoResolver to be used by the Signature when it needs to find a key to be used to validate a signature

void DSIGSignature::setPrettyPrint (  bool  flag  )

Set Pretty Print. The pretty print functions controls whether the library will output CR/LF after the elements it adds to a document By default the library will do pretty printing (flag is true) Parameters: flag  Value to set for Pretty Printing (true = do pretty printing)

void DSIGSignature::setSigningKey (  XSECCryptoKey *  k  )

Externally set the signing/verification key. Used prior to a verify or sign operation to set the signature key (public or private respectively) to be used for the operation. Note: Once passed in via this call, the key is owned by the Signature. It will deleted when a new key is loaded or the signature is released. See also: verify sign

void DSIGSignature::setURIResolver (  XSECURIResolver *  resolver  )

Register a URIResolver. Registers a URIResolver to be used by the Signature when dereferencing a URI in a Reference element

void DSIGSignature::setXPFNSPrefix (  const XMLCh *  prefix  )

Set the prefix be used for the XPath-Filter2 namespace. The XPathFilter definition uses its own namespace. This method can be used to set the prefix that the library will use when creating elements in this namespace xmlns:ds="http://www.w3.org/2002/06/xmldsig-filter2" If no prefix is set, the default namespace will be used See also: createBlankSignature Parameters: prefix  The UTF-16 encoided NS prefix to use for the XPath filter nodes

void DSIGSignature::sign (  void   )

Sign a DSIGSignature DOM structure. The sign function will create the reference hash values and signature value in a DOM structure previously created via a load or createBlankSignature call It performs the following operations : Iterate through each reference, calculate and set the hash value; Iterate through references contained in <manifest> elements and set their values; Calculate the hash of the <SignedInfo> element; and Calculate (and set) the signature value given the hash previously calculated. Note: The key to use for signing must have been set prior to call to sign using setSigningKey Exceptions: XSECException  (for errors during the XML formatting and loading) XSECCryptoException  (for errors during the cryptographic operations) See also: setSigningKey load getErrMsgs

bool DSIGSignature::verify (  void   )

Verify that a signature is valid. The verify function will validate the signature of an XML document previously loaded into the DSIGSignature structure via a load. It performs the following operations : Iterate through each reference and validate the hash; Iterate through references contained in <manifest> elements; Calculate the hash of the <SignedInfo> element; and Validate the signature of the hash previously calculated. Returns: true/false true = Signature (and all references) validated correctly. false = Signature validation failed. An error list can be found via a call to getErrMsgs. See also: load getErrMsgs

bool DSIGSignature::verifySignatureOnly (  void   )

Verify a signature is valid (skip references). This function is almost the same as verify except it will skip the reference checks. See also: load verify

---

Friends And Related Function Documentation

friend class XSECProvider [friend]

---

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

• DSIGSignature.hpp

---