---

DSIGSignature Class Reference
[Main Signature API]

The main class used for manipulating XML Digital Signatures. More...

#include <DSIGSignature.hpp>

Collaboration diagram for DSIGSignature:

[legend]List of all members.

Public Methods
Load and Setup Functions
void	load (void)
	Load the signature information from the DOM source. More...
void	setSigningKey (XSECCryptoKey *k)
	Externally set the signing/verification key. More...
Signature Operations
bool	verify (void)
	Verify that a signature is valid. More...
bool	verifySignatureOnly (void)
	Verify a signature is valid (skip references). More...
void	sign (void)
	Sign a DSIGSignature DOM structure. More...
Functions to create and manipulate signature elements.
void	setDSIGNSPrefix (char *prefix)
	Set the prefix be used for the DSIG namespace. More...
DOMElement *	createBlankSignature (DOMDocument *doc, canonicalizationMethod cm=CANON_C14N_NOC, signatureMethod sm=SIGNATURE_DSA, hashMethod hm=HASH_SHA1)
	Create a <Signature> DOM structure. More...
DSIGReference *	createReference (char *URI, hashMethod hm=HASH_SHA1, char *type=NULL)
	Add a new reference to the end of the list of <Reference> nodes. More...
General and Information functions.
unsigned int	calculateSignedInfoHash (unsigned char *hashBuf, unsigned int hashBufLen)
	Get the hash of the Signed Value. More...
DSIGReferenceList *	getReferenceList (void)
	Return the reference list for outside use. More...
XSECBinTXFMInputStream *	makeBinInputStream (void) const
	Create an input stream from SignedInfo. More...
safeBuffer &	getErrMsgsSB (void)
	Get the Error messages from the last verify. More...
const safeBuffer &	getDSIGNSPrefix ()
	Get the NS Prefix being used for DSIG elements. More...
DOMDocument *	getParentDocument ()
XSECSafeBufferFormatter *	getSBFormatter (void)
	Helper function for sub Classes. More...
Resolver manipulation
void	setURIResolver (XSECURIResolver *resolver)
	Register a URIResolver. More...
XSECURIResolver *	getURIResolver (void)
	Return a pointer to the resolver being used. More...
void	setKeyInfoResolver (XSECKeyInfoResolver *resolver)
	Register a KeyInfoResolver. More...
XSECKeyInfoResolver *	getKeyInfoResolver (void)
	Return a pointer to the resolver being used. More...
KeyInfo Element Manipulation
DSIGKeyInfoList *	getKeyInfoList ()
	Get the list of <KeyInfo> elements. More...
void	clearKeyInfo (void)
	Clear out all KeyInfo elements in the signature. More...
DSIGKeyInfoValue *	appendDSAKeyValue (const char *P, const char *Q, const char *G, const char *Y)
	Append a DSA KeyValue element. More...
DSIGKeyInfoX509 *	appendX509Data (void)
	Append a X509Data element. More...
DSIGKeyInfoName *	appendKeyName (const char *name)
	Append a KeyName element. More...
Protected Methods
Constructors and Destructors
	DSIGSignature (DOMDocument *doc, DOMNode *sigNode)
	Contructor for use with existing XML signatures or templates. More...
	~DSIGSignature ()
Friends
class	XSECProvider

---

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.

---

Constructor & Destructor Documentation

DSIGSignature::DSIGSignature (  DOMDocument *    doc, 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 char *    P, const char *    Q, const char *    G, const char *    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 char *    name )

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

DOMElement* DSIGSignature::createBlankSignature (  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 (  char *    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.

const safeBuffer& DSIGSignature::getDSIGNSPrefix (    )  [inline]

Get the NS Prefix being used for DSIG elements. Returns: The prefix in a safeBuffer See also: setDSIGNSPrefix

safeBuffer& DSIGSignature::getErrMsgsSB (  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 returned object is owned by the caller and needs to be deleted. Returns: A reference to the safeBuffer containing the error strings.

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

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.

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

XSECURIResolver* DSIGSignature::getURIResolver (  void    )

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

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::setDSIGNSPrefix (  char *    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 NS prefix to use for the XML Digital Signature nodes

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

---