Main Page   Modules   Class Hierarchy   Compound List   File List   Compound Members   File Members   Related Pages  

DSIGSignature Class Reference
[Main Signature API]

#include <DSIGSignature.hpp>

Collaboration diagram for DSIGSignature:

Collaboration graph
[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 Methods

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.

DOMElement * createBlankSignature (DOMDocument *doc, canonicalizationMethod cm=CANON_C14N_NOC, signatureMethod sm=SIGNATURE_DSA, hashMethod hm=HASH_SHA1)
 Create a <Signature> DOM structure.

DSIGReferencecreateReference (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 calculateSignedInfoHash (unsigned char *hashBuf, unsigned int hashBufLen)
 Get the hash of the Signed Value.

DSIGReferenceListgetReferenceList (void)
 Return the reference list for outside use.

XSECBinTXFMInputStreammakeBinInputStream (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.

DOMDocument * getParentDocument ()
canonicalizationMethod getCanonicalizationMethod (void)
 Get canonicalisation algorithm.

hashMethod getHashMethod (void)
 Get the hash method.

signatureMethod getSignatureMethod (void)
 Get the signature method.

XSECSafeBufferFormattergetSBFormatter (void)
 Helper function for sub Classes.

Resolver manipulation
void setURIResolver (XSECURIResolver *resolver)
 Register a URIResolver.

XSECURIResolvergetURIResolver (void)
 Return a pointer to the resolver being used.

void setKeyInfoResolver (XSECKeyInfoResolver *resolver)
 Register a KeyInfoResolver.

XSECKeyInfoResolvergetKeyInfoResolver (void)
 Return a pointer to the resolver being used.

KeyInfo Element Manipulation
DSIGKeyInfoListgetKeyInfoList ()
 Get the list of <KeyInfo> elements.

void clearKeyInfo (void)
 Clear out all KeyInfo elements in the signature.

DSIGKeyInfoValueappendDSAKeyValue (const XMLCh *P, const XMLCh *Q, const XMLCh *G, const XMLCh *Y)
 Append a DSA KeyValue element.

DSIGKeyInfoValueappendRSAKeyValue (const XMLCh *modulus, const XMLCh *exponent)
 Append a RSA KeyValue element.

DSIGKeyInfoX509appendX509Data (void)
 Append a X509Data element.

DSIGKeyInfoNameappendKeyName (const XMLCh *name)
 Append a KeyName element.


Protected Methods

Constructors and Destructors
 DSIGSignature (DOMDocument *doc, DOMNode *sigNode)
 Contructor for use with existing XML signatures or templates.

 ~DSIGSignature ()

Friends

class XSECProvider


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

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

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.

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

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   [inline]
 

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   [inline]
 

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

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

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

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 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::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:
Generated on Wed May 7 21:44:03 2003 for XML-Security-C by doxygen1.2.18