blautenb 2003/02/22 03:17:23
Modified: c/src/dsig DSIGKeyInfo.hpp DSIGReferenceList.cpp
DSIGReferenceList.hpp DSIGSignedInfo.hpp
c/src/framework XSECW32Config.hpp
Log:
Updated Doxy docs
Revision Changes Path
1.3 +86 -11 xml-security/c/src/dsig/DSIGKeyInfo.hpp
Index: DSIGKeyInfo.hpp
===================================================================
RCS file: /home/cvs/xml-security/c/src/dsig/DSIGKeyInfo.hpp,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- DSIGKeyInfo.hpp 9 Feb 2003 11:13:47 -0000 1.2
+++ DSIGKeyInfo.hpp 22 Feb 2003 11:17:21 -0000 1.3
@@ -64,9 +64,7 @@
*
* Author(s): Berin Lautenbach
*
- * $ID$
- *
- * $LOG$
+ * $Id$
*
*/
@@ -83,11 +81,37 @@
class DSIGSignature;
+/**
+ * @ingroup pubsig
+ * @{
+ */
+
+/**
+ * @brief Base class for <Key*> nodes in a KeyInfo list.
+ *
+ * Digital signatures can have a number of KeyInfo elements that are
+ * used to communicate information about what key to use between the
+ * signer and the validator.
+ *
+ * In the XML-Security-C libary, KeyInfo elements are only used for
+ * holding information about keys. They do not in themselves perform
+ * any cryptographic function.
+ *
+ */
+
+
class DSIG_EXPORT DSIGKeyInfo {
public:
- // To determine key type
+ /**
+ * \brief List of potential KeyInfo types
+ *
+ * The keyIntoType enumerated type defines the KeyInfo types known by
+ * the XML-Security-C library.
+ *
+ */
+
enum keyInfoType {
@@ -99,31 +123,82 @@
};
+public:
-protected:
-
- DOMNode * mp_keyInfoDOMNode;
- DSIGSignature * mp_parentSignature;
+ /** @name Constructors and Destructors */
+ //@{
-public:
+ /**
+ * \brief Construct from an owning signature
+ *
+ * All KeyInfo types take a constructor that names the owning signature.
+ *
+ * @param sig The signature that owns this element
+ */
DSIGKeyInfo(DSIGSignature * sig) {mp_keyInfoDOMNode = NULL;
mp_parentSignature = sig;}
+
+ /**
+ * \brief The Destructor
+ */
+
virtual ~DSIGKeyInfo() {};
- // Methods to get information
+ //@}
+
+ /** @name Get functions */
+ //@{
+
+ /**
+ * \brief Return type
+ *
+ * Can be used to find what type of KeyInfo this is
+ */
virtual keyInfoType getKeyInfoType(void) = 0;
+
+ /**
+ * \brief Return the DOMNode that heads up this DOMNode
+ */
+
virtual const DOMNode *getKeyInfoDOMNode() {return mp_keyInfoDOMNode;}
+
+ /**
+ * \brief Return the name of this key
+ *
+ * For those KeyInfo types that have a keyname, this function should
return
+ * it. For certificates, this may be the DN.
+ *
+ * @returns A pointer to a buffer containing the name
+ */
+
virtual const XMLCh * getKeyName(void) = 0;
- // Load/Set
+ //@}
+
+ /** @name Load and Set */
+ //@{
+
+ /**
+ * \brief Load the DOM structures.
+ *
+ * Used by the library to instruct the object to load information from
+ * the DOM nodes
+ */
virtual void load() = 0;
+protected:
+
+ DOMNode * mp_keyInfoDOMNode;
+ DSIGSignature * mp_parentSignature;
+
private:
DSIGKeyInfo();
};
+
+/** @} */
1.3 +7 -38 xml-security/c/src/dsig/DSIGReferenceList.cpp
Index: DSIGReferenceList.cpp
===================================================================
RCS file: /home/cvs/xml-security/c/src/dsig/DSIGReferenceList.cpp,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- DSIGReferenceList.cpp 9 Feb 2003 11:13:47 -0000 1.2
+++ DSIGReferenceList.cpp 22 Feb 2003 11:17:22 -0000 1.3
@@ -64,9 +64,7 @@
*
* Author(s): Berin Lautenbach
*
- * $ID$
- *
- * $LOG$
+ * $Id$
*
*/
@@ -106,46 +104,17 @@
DSIGReference * DSIGReferenceList::removeReference(size_type index) {
- if (index < m_referenceList.size())
- return m_referenceList[index];
-
- return NULL;
-
-}
-
-/*
-DSIGReference * DSIGReferenceList::getFirstReference() {
-
- DSIGReference * retValue;
-
- m_iterator = m_referenceList.begin();
-
- if (m_iterator != m_referenceList.end()) {
-
- retValue = *m_iterator;
- m_iterator++;
- return retValue;
+ DSIGReference * ret = NULL;
+ if (index < m_referenceList.size()) {
+ ret = m_referenceList[index];
+ m_referenceList.erase(m_referenceList.begin() + index - 1);
+
}
- return NULL;
-
-}
-
-DSIGReference * DSIGReferenceList::getNextReference() {
-
- DSIGReference * retValue;
-
- if (m_iterator == m_referenceList.end())
- return NULL;
-
- retValue = *m_iterator;
- m_iterator++;
-
- return retValue;
+ return ret;
}
-*/
DSIGReference * DSIGReferenceList::item(ReferenceListVectorType::size_type
index) {
1.3 +84 -10 xml-security/c/src/dsig/DSIGReferenceList.hpp
Index: DSIGReferenceList.hpp
===================================================================
RCS file: /home/cvs/xml-security/c/src/dsig/DSIGReferenceList.hpp,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- DSIGReferenceList.hpp 9 Feb 2003 11:13:47 -0000 1.2
+++ DSIGReferenceList.hpp 22 Feb 2003 11:17:22 -0000 1.3
@@ -64,9 +64,7 @@
*
* Author(s): Berin Lautenbach
*
- * $ID$
- *
- * $LOG$
+ * $Id$
*
*/
@@ -83,6 +81,25 @@
class DSIGReference;
+/**
+ * @ingroup pubsig
+ * @{
+ */
+
+/**
+ * @brief Holds a list of reference elements.
+ *
+ * The library holds a Signature's list of references using this class.
+ * Manifest lists are similarly held. Developers can obtain the
+ * list from the Signature library using DSIGSignature::getReferenceList
+ * and then iterate through each reference.
+ *
+ * The library also uses the List as the owner of the memory associated
+ * with References. So when a list is deleted, the references are deleted
+ * at the same time.
+ *
+ */
+
class DSIG_EXPORT DSIGReferenceList {
public:
@@ -99,30 +116,87 @@
typedef size_t size_type;
#endif
- // Constructors and Destructors
+ /** @name Constructors and Destructors */
+ //@{
+
+ /**
+ * \brief Construct a list
+ */
DSIGReferenceList();
+ /**
+ * \brief Destroy a list.
+ *
+ * Standard destructor to close down the list.
+ *
+ * @note Destroys the references as well as the list
+ */
+
~DSIGReferenceList();
- // Actions
+ //@}
+
+ /** @name List manipulation */
+ //@{
+ /**
+ * \brief Add a reference to the list
+ *
+ * Appends the reference to the end of the list and takes ownership
+ * of associated memory.
+ */
+
void addReference(DSIGReference * ref);
+
+ /**
+ * \brief Remove a reference from the list
+ *
+ * Removes the reference at the index point and returns a pointer
+ * to the reference removed.
+ *
+ * @note This also releases ownership. It is the responsibility of
+ * the caller to ensure the reference is deleted.
+ *
+ * @note This does not currently delete the reference from the
Signature
+ *
+ * @param index Point in the list to remove
+ */
+
DSIGReference * removeReference(size_type index);
+
+ /**
+ * \brief Return a reference from the list
+ *
+ * Gets the reference at point index in the list
+ *
+ * @param index The pointer into the list
+ */
+
DSIGReference * item(size_type index);
- //DSIGReference * getFirstReference(void); // Iteration
start
- //DSIGReference * getNextReference(void); //
Iterator continue
+
+ /**
+ * \brief Find the number of elements in the list
+ *
+ * @returns The number of elements in the list
+ */
+
size_type getSize();
+ /**
+ * \brief Clear out the list
+ *
+ * Simply clears the list. Does not delete the reference elements
themselves.
+ */
+
bool empty();
-
- // Get information
+ //@}
private:
ReferenceListVectorType m_referenceList;
- //ReferenceListVectorType::iterator m_iterator;
+
};
1.4 +162 -12 xml-security/c/src/dsig/DSIGSignedInfo.hpp
Index: DSIGSignedInfo.hpp
===================================================================
RCS file: /home/cvs/xml-security/c/src/dsig/DSIGSignedInfo.hpp,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- DSIGSignedInfo.hpp 22 Feb 2003 08:47:23 -0000 1.3
+++ DSIGSignedInfo.hpp 22 Feb 2003 11:17:22 -0000 1.4
@@ -89,46 +89,195 @@
class DSIGSignature;
+/**
+ * @ingroup pubsig
+ * @{
+ */
+
+/**
+ * @brief Constructs and holds a SignedInfo.
+ *
+ * The <SignedInfo> node is the container for all the information
+ * that is signed. It contains the ReferenceList and information
+ * on the signature and canonicalisation method for the signature.
+ *
+ * Generally this class should not be manipulated directly.
+ *
+ */
+
class DSIGSignedInfo {
public:
- // Constructors and Destructors
+ /** @name Constructors and Destructors */
+ //@{
+
+ /**
+ * \brief Constructor for existing nodes
+ *
+ * Called by the library to construct a SignedInfo in cases
+ * where the DOM Nodes exist and need to be loaded
+ *
+ * @param doc The document containing the structure to be loaded
+ * @param pFormatter A safeBuffer formatter that will translate to UTF-8
+ * @param signedInfoNode The node at the top of the SignedInfo tree
fragment
+ * @param parentSignature The signature that owns me
+ */
DSIGSignedInfo(DOMDocument *doc,
XSECSafeBufferFormatter * pFormatter,
DOMNode *signedInfoNode,
DSIGSignature * parentSignature);
- // For a blank signature
+
+ /**
+ * \brief Constructor for building from scratch
+ *
+ * Will set up the class in preparation for building the
+ * DOM structure
+ *
+ * @param doc The document to use to construct
+ * @param pFormatter Formatter to use to translate to UTF-8
+ * @param parentSignature The owning Signature
+ */
DSIGSignedInfo(DOMDocument *doc,
XSECSafeBufferFormatter * pFormatter,
DSIGSignature * parentSignature);
+ /**
+ * \brief Destructur
+ *
+ * Delete - but does not destroy the DOM Nodes
+ *
+ */
+
~DSIGSignedInfo();
- // Actions
+ //@}
+
+ /** @name Create and Set */
+ //@{
+
+ /**
+ * \brief Load from DOM
+ *
+ * Load the SignedInfo from the DOM Document
+ *
+ * Does not do any verification of signatures or references -
+ * simply loads the values
+ */
+
+ void load(void);
+
+ /**
+ * \brief Verify the SignedInfo
+ *
+ * Validates each reference contained in the SignedInfo. Does not
+ * validate the signature itself - this is done by DSIGSignature
+ *
+ * @param errStr The safeBuffer that error messages should be written
to.
+ */
- void load(void); // Load the signed info
from the DOM source
bool verify(safeBuffer &errStr);
+
+ /**
+ * \brief Hash the reference list
+ *
+ * Goes through each reference in the SignedInfo (including referenced
+ * manifests), performs the digest operation and adds the digest
+ * to the reference element
+ */
+
void hash(void); // Setup hashes for
each Reference element
- // Get information
+ /**
+ * \brief Create an empty SignedInfo
+ *
+ * Creates the DOM structure for a SignedInfo
+ *
+ * Builds the DOM structures and sets the control
+ * structures of the SignedInfo
+ *
+ * @param cm The canonicalisation method to set the SignedInfo as
+ * @param sm Signature Method to use
+ * @param hm Hash method to use (for the SignedInfo, not the references)
+ */
+
+ DOMElement *createBlankSignedInfo(canonicalizationMethod cm,
+ signatureMethod sm,
+ hashMethod hm);
+
+ /**
+ * \brief Create a reference to add to the SignedInfo
+ *
+ * Called by DSIGSignature to create and enter a new reference element
+ *
+ * @param URI What the reference references
+ * @param hm Digest method to use for the reference
+ * @type Reference type
+ */
+
+ DSIGReference * createReference(const XMLCh * URI,
+ hashMethod hm, char * type);
+
+ //@}
+
+ /** @name Getter functions */
+ //@{
+
+ /**
+ * \brief Get the node pointing to the top of the DOM fragment
+ *
+ * @returns the SignedInfo node
+ */
DOMNode *getDOMNode(void);
+
+ /**
+ * \brief Get the canonicalisation method
+ *
+ * @returns Canonicalisation method
+ */
+
canonicalizationMethod getCanonicalizationMethod(void);
+
+ /**
+ * \brief Get the hash method
+ *
+ * @returns the Hash (digest) Method
+ */
+
hashMethod getHashMethod(void);
+
+ /**
+ * \brief Get the signature method
+ *
+ * @returns the Signature method
+ */
+
signatureMethod getSignatureMethod(void);
+
+ /**
+ * \brief Get HMAC length
+ *
+ * HMAC signatures can be truncated to a nominated length.
+ * This returns the length used.
+ */
+
int getHMACOutputLength(void);
+
+ /**
+ * \brief Return the list of references
+ *
+ * Returns a pointer to the object holding the references
+ * contained in the SignedInfo
+ */
+
DSIGReferenceList *getReferenceList (void) {return mp_referenceList;}
- // Creation
- DOMElement *createBlankSignedInfo(canonicalizationMethod cm,
- signatureMethod sm,
- hashMethod hm);
- DSIGReference * createReference(const XMLCh * URI,
- hashMethod hm, char * type);
+ //@}
+
private:
@@ -150,5 +299,6 @@
};
+/** @} */
#endif /* DSIGSIGNEDINFO_INCLUDE */
1.4 +3 -2 xml-security/c/src/framework/XSECW32Config.hpp
Index: XSECW32Config.hpp
===================================================================
RCS file: /home/cvs/xml-security/c/src/framework/XSECW32Config.hpp,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- XSECW32Config.hpp 21 Feb 2003 11:53:08 -0000 1.3
+++ XSECW32Config.hpp 22 Feb 2003 11:17:23 -0000 1.4
@@ -88,4 +88,5 @@
/* #define HAVE_UNISTD_H */
/* Windows direct.h */
-#define HAVE_DIRECT_H 1
\ No newline at end of file
+#define HAVE_DIRECT_H 1
+
