Added more comments to the common files

9 files changed, 349 insertions, 15 deletions

diff --git a/common/certinfo.c b/common/certinfo.c
index 0691a7a..93766b3 100644
--- a/common/certinfo.c
+++ b/common/certinfo.c
@@ -19,6 +19,16 @@
  *
  */
 
+/**
+ * @file   certinfo.c
+ * @author David Sommerseth <dazo@users.sourceforge.net>
+ * @date   2008-08-06
+ *
+ * @brief  Functions for parsing X.509 subject information
+ *
+ */
+
+
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
@@ -29,6 +39,13 @@
 
 #define comp_attrib(s, v) ( (v == NULL || strlen_nullsafe(v) < 1) ? 0 : (strcmp(v, s) == 0) )
 
+/**
+ * Parses a X.509 subject string into a certinfo structure
+ *
+ * @param input  String containing a X.509 subject line
+ *
+ * @return Pointer to a certinfo structure containing the information
+ */
 certinfo *parse_tlsid(const char *input) {
         char tmp[130], *mainp, *origptr, *sub, *tok, *tok2;
         certinfo *ret = NULL;
@@ -77,6 +94,12 @@ certinfo *parse_tlsid(const char *input) {
         return ret;
 }
 
+
+/**
+ * Frees up the memory used by a certinfo structure
+ *
+ * @param p Pointer to a certinfo structure to be freed
+ */
 void free_certinfo(certinfo *p) {
         if( p == NULL )
                 return;
diff --git a/common/eurephia_getsym.c b/common/eurephia_getsym.c
index f4a8b9d..cf9f244 100644
--- a/common/eurephia_getsym.c
+++ b/common/eurephia_getsym.c
@@ -19,6 +19,14 @@
  *
  */
 
+/**
+ * @file   eurephia_getsym.c
+ * @author David Sommerseth <dazo@users.sourceforge.net>
+ * @date   2008-08-10
+ *
+ * @brief  Helper functions for handling dynamic loaded objects (.so files)
+ *
+ */
 
 #include <stdio.h>
 #include <dlfcn.h>
@@ -26,6 +34,15 @@
 #include <eurephia_context.h>
 #include "eurephia_log.h"
 
+/**
+ * Retrieves a function pointer to a given function name
+ *
+ * @param ctx    eurephiaCTX
+ * @param dlh    Handler which dlopen() returned
+ * @param symnam Name of the function to find
+ *
+ * @return Returns a pointer to the function if it was found, otherwise NULL is returned.
+ */
 void *eGetSym(eurephiaCTX *ctx, void *dlh, const char *symnam)
 {
         void *func = NULL;
diff --git a/common/eurephia_log.c b/common/eurephia_log.c
index 8eea829..76dff8c 100644
--- a/common/eurephia_log.c
+++ b/common/eurephia_log.c
@@ -19,6 +19,16 @@
  *
  */
 
+/**
+ * @file   eurephia_log.c
+ * @author David Sommerseth <dazo@users.sourceforge.net>
+ * @date   2008-08-06
+ *
+ * @brief  Function for unified logging
+ *
+ */
+
+
 #include <stdio.h>
 #include <stdarg.h>
 #include <string.h>
@@ -39,11 +49,21 @@ const char *erp_logtypes[] = {
         "** * PANIC * ** \0"
 };
 
-// POSIX Mutex to avoild simultaneously logging activity from
+// POSIX Mutex to avoid simultaneously logging activity from
 // several threads at the same time
 pthread_mutex_t log_mutex = PTHREAD_MUTEX_INITIALIZER;
 
 // Simple log function ... Write log data to the context log file
+/**
+ * Simple log function which writes log data to the log file available in the eurephiaCTX
+ *
+ * @param ctx    eurephiaCTX
+ * @param logdst Log destination, can be LOG_INFO, LOG_DEBUG, LOG_WARNING, LOG_ERROR, 
+ *        LOG_CRITICAL, LOG_FATAL or LOG_PANIC
+ * @param loglvl Log level of the message.  If the eurephiaCTX has a lower log level setup
+ *        than what this parameter is set to, the message will not be logged.
+ * @param fmt    Contents of the log message (stdarg)
+ */
 void eurephia_log(eurephiaCTX *ctx, int logdst, int loglvl, const char *fmt, ... ) {
 
         // Only log if we have an open log file and which has high enough log level
@@ -53,13 +73,13 @@ void eurephia_log(eurephiaCTX *ctx, int logdst, int loglvl, const char *fmt, ...
                 time_t tstmp;
                 struct tm *loctstmp;
 
-                // Get timestamp
+                // Get time stamp
                 memset(&tstmp_str, 0, 200);
                 tstmp = time(NULL);
                 loctstmp = localtime(&tstmp);
                 if( loctstmp != NULL ) {
                         if( strftime(tstmp_str, 198, "%Y-%m-%d %H:%M:%S %Z", loctstmp) == 0 ) {
-                                snprintf(tstmp_str, 198, "(error getting timestamp string)");
+                                snprintf(tstmp_str, 198, "(error getting time stamp string)");
                         }
                 } else {
                         snprintf(tstmp_str, 198, "(error getting timestamp)");
diff --git a/common/eurephia_values.c b/common/eurephia_values.c
index 7f5d22c..3c7ac91 100644
--- a/common/eurephia_values.c
+++ b/common/eurephia_values.c
@@ -18,6 +18,15 @@
  *  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
  */
 
+/**
+ * @file   eurephia_values.c
+ * @author David Sommerseth <dazo@users.sourceforge.net>
+ * @date   2008-08-06
+ *
+ * @brief  Generic interface for handling key->value pairs
+ *
+ */
+
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
@@ -28,6 +37,11 @@
 #include <eurephia_log.h>
 
 
+/**
+ * Internal function. Makes sure a eurephiaVALUES stack is freed up
+ *
+ * @param vls Pointer to a eurephiaVALUES stack.
+ */
 void do_free_vals(eurephiaVALUES *vls) {
         if( vls->next != NULL ) {
                 do_free_vals(vls->next);
@@ -37,6 +51,14 @@ void do_free_vals(eurephiaVALUES *vls) {
         free_nullsafe(vls);
 }
 
+
+/**
+ * Function for freeing up an eurephiaVALUES stack.  This function is normally not called
+ * directly, but usually via the eFree_values(...) macro.
+ *
+ * @param ctx  eurephiaCTX
+ * @param vls  Pointer to a eurephiaVALUES stack to be freed.
+ */
 void eFree_values_func(eurephiaCTX *ctx, eurephiaVALUES *vls) {
         DEBUG(ctx, 31, "Function call: eFree_values(ctx, vls(%i))",
               (vls != NULL ? vls->evid : -1));
@@ -47,6 +69,15 @@ void eFree_values_func(eurephiaCTX *ctx, eurephiaVALUES *vls) {
         do_free_vals(vls);
 }
 
+
+/**
+ * Retrieve an eurephiaVALUES element for a given value key
+ *
+ * @param vls  Pointer to the eurephiaVALUES stack where to search for the element
+ * @param key  String containing the key name of the value requested.
+ *
+ * @return Returns an eurephiaVALUES element on success, otherwise NULL.
+ */
 eurephiaVALUES *eGet_valuestruct(eurephiaVALUES *vls, const char *key)
 {
         eurephiaVALUES *ptr = NULL;
@@ -66,6 +97,14 @@ eurephiaVALUES *eGet_valuestruct(eurephiaVALUES *vls, const char *key)
 }
 
 
+/**
+ * Retrieves the value of a given key from an eurephiaVALUES stack.
+ *
+ * @param vls  Pointer to an eurephiaVALUES stack where to search for the value
+ * @param key  String containing the key name of the value requested
+ *
+ * @return Returns a string (char *) with the requested value if found, otherwise NULL.
+ */
 char *eGet_value(eurephiaVALUES *vls, const char *key)
 {
         eurephiaVALUES *ptr = NULL;
@@ -75,6 +114,14 @@ char *eGet_value(eurephiaVALUES *vls, const char *key)
 }
 
 
+/**
+ * Creates a new eurephiaVALUES stack
+ *
+ * @param ctx    eurephiaCTX
+ * @param evgid  int value, giving the stack an ID number.  Useful when looking through log files later on.
+ *
+ * @return Returns an empty eurephiaVALUES struct on success, otherwise NULL.
+ */
 eurephiaVALUES *eCreate_value_space(eurephiaCTX *ctx, int evgid)
 {
         eurephiaVALUES *ptr = NULL;
@@ -83,7 +130,7 @@ eurephiaVALUES *eCreate_value_space(eurephiaCTX *ctx, int evgid)
 
         ptr = (eurephiaVALUES *) malloc(sizeof(eurephiaVALUES) + 2);
         if( ptr == NULL ) {
-                eurephia_log(ctx, LOG_PANIC, 0, "Could not allocate memory for a new eurephiaVALUE struct");
+                eurephia_log(ctx, LOG_PANIC, 0, "Could not allocate memory for a new eurephiaVALUES struct");
                 return NULL;
         }
         memset(ptr, 0, sizeof(eurephiaVALUES) + 2);
@@ -92,6 +139,14 @@ eurephiaVALUES *eCreate_value_space(eurephiaCTX *ctx, int evgid)
 }
 
 
+/**
+ * Adds a new eurephiaVALUES stack to another eurephiaVALUES stack.  If the evgid value differs, it will
+ * be overwritten with the value of the destination stack.
+ *
+ * @param ctx    eurephiaCTX
+ * @param vls    Destination eurephiaVALUES stack
+ * @param newval Source eurephiaVALUES stack
+ */
 void eAdd_valuestruct(eurephiaCTX *ctx, eurephiaVALUES *vls, eurephiaVALUES *newval) {
         eurephiaVALUES *ptr = NULL;
         int vid = 0;
@@ -121,6 +176,15 @@ void eAdd_valuestruct(eurephiaCTX *ctx, eurephiaVALUES *vls, eurephiaVALUES *new
         }
 }
 
+
+/**
+ * Adds a new key/value pair to an eurephiaVALUES stack
+ *
+ * @param ctx  eurephiaCTX
+ * @param vls  Destination eurephiaVALUES stack
+ * @param key  Key name for the value being stored
+ * @param val  Value to be stored
+ */
 void eAdd_value(eurephiaCTX *ctx, eurephiaVALUES *vls, const char *key, const char *val)
 {
         eurephiaVALUES *ptr = NULL;
diff --git a/common/eurephia_xml.c b/common/eurephia_xml.c
index a4c6011..8e34050 100644
--- a/common/eurephia_xml.c
+++ b/common/eurephia_xml.c
@@ -19,6 +19,16 @@
  *
  */
 
+/**
+ * @file   eurephia_xml.c
+ * @author David Sommerseth <dazo@users.sourceforge.net>
+ * @date   2008-12-15
+ *
+ * @brief  Generic XML parser functions
+ *
+ *
+ */
+
 #ifdef HAVE_LIBXML2
 #include <stdarg.h>
 #include <string.h>
@@ -31,6 +41,15 @@
 #include <eurephia_log.h>
 #include <eurephia_xml.h>
 
+
+/**
+ * Retrieves a given XML node attribute/property
+ *
+ * @param attr xmlAttr pointer from an xmlNode pointer.
+ * @param key  The attribute name to search for
+ *
+ * @return The value of the found attribute.  If not found, NULL is returned.
+ */
 char *xmlGetAttrValue(xmlAttr *attr, const char *key) {
         xmlAttr *aptr;
         xmlChar *x_key = NULL;
@@ -49,6 +68,15 @@ char *xmlGetAttrValue(xmlAttr *attr, const char *key) {
         return NULL;
 }
 
+
+/**
+ * Loops through a xmlNode chain to look for a given tag.  The search is not recursive.
+ *
+ * @param node xmlNode pointer where to look
+ * @param key  the name of the XML tag to find
+ *
+ * @return xmlNode pointer to the found xmlNode.  NULL is returned if not found.
+ */
 xmlNode *xmlFindNode(xmlNode *node, const char *key) {
         xmlNode *nptr = NULL;
         xmlChar *x_key = NULL;
@@ -71,6 +99,18 @@ xmlNode *xmlFindNode(xmlNode *node, const char *key) {
 }
 
 
+/**
+ * Simple function for creating a new eurephia XML document.  On failure, this function will cause
+ * an assertion error.
+ *
+ * @param ctx           eurephiaCTX
+ * @param format        Format version of the eurephia document (int value)
+ * @param eurephiaRoot  The name of the root tag of the resulting XML document
+ * @param doc           xmlDoc pointer to the new document
+ * @param root_n        xmlNode pointer to the root element of the document
+ *
+ * @return returns always 1.
+ */
 int eurephiaXML_CreateDoc(eurephiaCTX *ctx, int format, const char *eurephiaRoot,
                           xmlDoc **doc, xmlNode **root_n)
 {
@@ -95,6 +135,17 @@ int eurephiaXML_CreateDoc(eurephiaCTX *ctx, int format, const char *eurephiaRoot
 }
 
 
+/**
+ * Get the root node of an eurephia XML document.  This function also validates the basic structure
+ * of the document and makes sure the format version of the document is valid.
+ *
+ * @param ctx         eurephiaCTX
+ * @param doc         xmlDoc pointer to the XML document
+ * @param nodeset     The expected root node to be found
+ * @param req_format  The minimum format version to be accepted
+ *
+ * @return Returns pointer to the given xmlNode tag.  On failure, NULL is returned.
+ */
 xmlNode *eurephiaXML_getRoot(eurephiaCTX *ctx, xmlDoc *doc, const char *nodeset, int req_format) {
         xmlNode *root = NULL;
         char *xmlformat_str = NULL;
@@ -119,6 +170,16 @@ xmlNode *eurephiaXML_getRoot(eurephiaCTX *ctx, xmlDoc *doc, const char *nodeset,
 }
 
 
+/**
+ * Creates a simple result message, formatted as an XML document.
+ *
+ * @param ctx   eurephiaCTX
+ * @param type  Can be exmlRESULT or exmlERROR.  The former is used for informational messages.
+ * @param fmt   stdarg format string
+ *
+ * @return Returns a valid eurephia XML document as a properly formatted result message.
+ *         On failure, NULL is returned
+ */
 xmlDoc *eurephiaXML_ResultMsg(eurephiaCTX *ctx, exmlResultType type, const char *fmt, ... ) {
         va_list ap;
         xmlChar msg[2050], *xmlfmt = NULL;
@@ -154,12 +215,27 @@ xmlDoc *eurephiaXML_ResultMsg(eurephiaCTX *ctx, exmlResultType type, const char
 }
 
 
+/**
+ * Return the text content of a given xmlNode
+ *
+ * @param n xmlNode to extract the value from.
+ *
+ * @return returns a char pointer with the text contents of an xmlNode.
+ */
 inline char *xmlExtractContent(xmlNode *n) {
         // FIXME: Should find better way how to return UTF-8 data
         return (char *) (((n != NULL) && (n->children != NULL)) ? n->children->content : NULL);
 }
 
 
+/**
+ * Get the text contents of a given xmlNode
+ *
+ * @param node An xmlNode pointer where to look for the contents
+ * @param key  Name of the tag to retrieve the content of.
+ *
+ * @return Returns a string with the text content, if the node is found.  Otherwise, NULL is returned.
+ */
 inline char *xmlGetNodeContent(xmlNode *node, const char *key) {
         return xmlExtractContent(xmlFindNode(node, key));
 }
diff --git a/common/eurephiadb_session_common.c b/common/eurephiadb_session_common.c
index abcd75a..8c18ceb 100644
--- a/common/eurephiadb_session_common.c
+++ b/common/eurephiadb_session_common.c
@@ -19,6 +19,16 @@
  *
  */
 
+/**
+ * @file   eurephiadb_session_common.c
+ * @author David Sommerseth <dazo@users.sourceforge.net>
+ * @date   2008-11-28
+ *
+ * @brief  Common functions for handling eurephia sessions.
+ *
+ */
+
+
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
@@ -31,7 +41,7 @@
 #include <eurephiadb_session_struct.h>
 
 
-#ifndef DRIVER_MODE   // Use the right declaration, depending on if we compile driver or plugin/exec
+#ifndef DRIVER_MODE   // Use the right declaration, depending on if we compile driver or plug-in/exec
 // Functions needed to be found in the database driver
 int (*eDBstore_session_value) (eurephiaCTX *ctx, eurephiaSESSION *session, int mode,
                                const char *key, const char *val);
@@ -40,8 +50,17 @@ int eDBstore_session_value (eurephiaCTX *ctx, eurephiaSESSION *session, int mode
                                const char *key, const char *val);
 #endif
 
-// Adds or updates a key in the eurephiaVALUES stack.  Database is updated before the stack is updated.
-// If database fails, the stack is not updated.
+/**
+ * Adds or updates a key in the eurephiaVALUES stack.  Database is updated before the stack is updated.
+ * If database fails, the stack is not updated.
+ *
+ * @param ctx     eurephiaCTX
+ * @param session eurephiaSESSION, which contains information about the current user session
+ * @param key     key name of the value to be stored
+ * @param val     value to be stored
+ *
+ * @return Returns 1 on success, otherwise 0.
+ */
 int eDBset_session_value(eurephiaCTX *ctx, eurephiaSESSION *session, const char *key, const char *val) {
         eurephiaVALUES *svals = NULL;
 
@@ -95,7 +114,13 @@ int eDBset_session_value(eurephiaCTX *ctx, eurephiaSESSION *session, const char
 }
 
 
-// Free up the memory used by a session structure
+/**
+ * Free up the memory used by a session structure.  This is normally not called directly, but called via the
+ * eDBfree_session(...) macro.
+ *
+ * @param ctx      eurephiaCTX
+ * @param session  Pointer to the eurephiaSESSION structure to be freed.
+ */
 void eDBfree_session_func(eurephiaCTX *ctx, eurephiaSESSION *session) {
         if( session == NULL ) {
                 return;
diff --git a/common/passwd.c b/common/passwd.c
index 7887efb..70fc3d3 100644
--- a/common/passwd.c
+++ b/common/passwd.c
@@ -26,6 +26,17 @@
  *
  */
 
+/**
+ * @file   passwd.c
+ * @author David Sommerseth <dazo@users.sourceforge.net>
+ * @author Ulrich Drepper <drepper@redhat.com>
+ * @date   2009-03-21
+ *
+ * @brief  Functions for generating SHA512 hashes from clear-text values.  Parts of this
+ *         code is based on Ulrich Dreppers paper for implementing SHA512 hashing in glibc.
+ *
+ */
+
 #ifndef _GNU_SOURCE
 #define _GNU_SOURCE
 #endif
@@ -67,6 +78,14 @@
 static const char b64t[64] =
 "./0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
 
+
+/**
+ * Generates a phase2 salt value from a password.
+ *
+ * @param pwd  Input hash
+ *
+ * @return Returns an int value containing the phase2 salt information
+ */
 inline unsigned int get_salt_p2(const char *pwd) {
         int n = 0;
         long int saltinfo_p2 = 0, t = 0;
@@ -82,12 +101,34 @@ inline unsigned int get_salt_p2(const char *pwd) {
         return saltinfo_p2;
 }
 
+
+/**
+ *  Packs the hashing rounds value and salt length as a 8 byte hex value, and "scrambled" with
+ *  a phase2 salt information.
+ *
+ * @param buf     Return buffer where the salt info will be returned
+ * @param buflen  Size of the buffer
+ * @param rounds  Number of hashing rounds
+ * @param saltlen Length of the SHA512 salt
+ * @param pwd     Password of the user
+ *
+ * @return Returns the length of the salt information in bytes.
+ */
 int pack_saltinfo(char *buf, int buflen, int rounds, int saltlen, const char *pwd) {
         assert((buf != NULL) && (buflen > 0));
         snprintf(buf, buflen, "%08x%c", (unsigned int)(((rounds<<8)+saltlen) ^ 0xAAAAAAAA) ^ get_salt_p2(pwd), 0);
         return strlen_nullsafe(buf);
 }
 
+
+/**
+ * This function will unpack the salt information and "unscramble" it with a given password
+ *
+ * @param insalt  Input eurephia SHA512 salt string
+ * @param pwd     Users password
+ *
+ * @return Returns the decoded salt information, containing hashing rounds and salt length.
+ */
 unsigned int unpack_saltinfo(const char *insalt, const char *pwd) {
         unsigned int in_salt_prefix = 0;
 
@@ -101,6 +142,16 @@ unsigned int unpack_saltinfo(const char *insalt, const char *pwd) {
         }
 }
 
+
+/**
+ * Generates a number of random characters, used to create an even more unpredictable hashing salt
+ *
+ * @param ctx      eurephiaCTX
+ * @param saltstr  Return buffer where the salt will be placed (char *)
+ * @param len      Size of the buffer
+ *
+ * @return Returns 1 on success, otherwise 0
+ */
 int gen_randsaltstr(eurephiaCTX *ctx, char *saltstr, int len) {
         static const char randchars[] = "7+q2wertyuiopasd5fghj1kl<zxcvbnm,3.-!#%&/()9=?ZXCVBNM;:_ASD4FGHJK6L*QWE8RTYUI0OP>@£$\0";
         unsigned char *rand = NULL, *ptr2 = NULL;
@@ -126,6 +177,18 @@ int gen_randsaltstr(eurephiaCTX *ctx, char *saltstr, int len) {
         return 1;
 }
 
+
+/**
+ * Internal SHA512 hashing function.  Does the real hashing job
+ *
+ * @param key            The password of the user
+ * @param salt           Salt to be used when generating the SHA512 hash
+ * @param maxrounds_cfg  Maximum configured hashing rounds
+ * @param buffer         Buffer where to put the SHA512 result
+ * @param buflen         Size of the buffer
+ *
+ * @return  Returns a pointer to the buffer, or NULL on failure.
+ */
 inline char *sha512_crypt_r(const char *key, const char *salt, size_t maxrounds_cfg, char *buffer, int buflen)
 {
         unsigned char alt_result[64]
@@ -157,22 +220,19 @@ inline char *sha512_crypt_r(const char *key, const char *salt, size_t maxrounds_
         // The drawback is if the maxrounds later on is changed to a value which is:
         //             passwordsalt_rounds > maxrounds_cfg * 1.5
         // these passwords will be invalidated by that change.  This is considered
-        // to be a feature and not a bug.  The reason for mulitiplying by 1.5, is to
+        // to be a feature and not a bug.  The reason for multiplying by 1.5, is to
         // allow a little room for a degrading max rounds.
         //
         // Without this fix, a wrong password might take several seconds or minutes to
         // calculate.  This behaviour is not wanted as that wastes CPU cycles on something
         // we know is wrong.  But to avoid quiting too quickly and to slow down
-        // bruteforce attacks directly on eurephia, we add 1 seconds sleep.
+        // brute-force attacks directly on eurephia, we add 1 seconds sleep.
         //
         if( rounds > (maxrounds_cfg * 1.5) ) {
                 sleep(1);
                 return NULL;
         }
 
-        //printf("%-8.8s == (%ld, %i)  [%02x, %06x]\n",
-        //       salt, (long int)rounds, (int)salt_len, (int)rounds, (int)salt_len);
-
         if ((key - (char *) 0) % __alignof__ (uint64_t) != 0) {
                 char *tmp = (char *) alloca (key_len + __alignof__ (uint64_t));
                 key = copied_key = memcpy (tmp + __alignof__ (uint64_t)
@@ -373,7 +433,18 @@ inline char *sha512_crypt_r(const char *key, const char *salt, size_t maxrounds_
 }
 
 
-/* The main password hashing for eurephia passwords */
+/**
+ * The main SHA512 password hashing for eurephia passwords.  Suitable when passwords needs to be
+ * stored on disk.
+ *
+ * @param ctx  eurephiaCTX
+ * @param key  Users password
+ * @param salt Salt to be used when validating the password.  To generate a new SHA512 hash, set
+ *             this parameter to NULL
+ *
+ * @return Returns a string to a buffer containing the SHA512 hash.  This buffer must be cleared and
+ *         freed when no longer needed.
+ */
 char *eurephia_pwd_crypt(eurephiaCTX *ctx, const char *key, const char *salt) {
         /* We don't want to have an arbitrary limit in the size of the
            password.  We can compute an upper bound for the size of the
@@ -454,6 +525,17 @@ char *eurephia_pwd_crypt(eurephiaCTX *ctx, const char *key, const char *salt) {
 }
 
 
+/**
+ * Very quick SHA512 hashing algorithm, to be used only when hashing is static and not suitable for
+ * storing of password hashes.
+ *
+ * @param salt  Salt to be used when generating the hashing
+ * @param pwd   Value to be hashed.
+ *
+ * @return  Returns a pointer to buffer containing the SHA512 hash.  This buffer must be cleared and freed
+ *          when no longer needed.
+ */
+
 char *eurephia_quick_hash(const char *salt, const char *pwd) {
         SHA512Context sha;
         uint8_t sha_res[SHA512_HASH_SIZE];
diff --git a/common/randstr.c b/common/randstr.c
index bb4fc1c..42886b1 100644
--- a/common/randstr.c
+++ b/common/randstr.c
@@ -19,6 +19,15 @@
  *
  */
 
+/**
+ * @file   randstr.c
+ * @author David Sommerseth <dazo@users.sourceforge.net>
+ * @date   2009-01-10
+ *
+ * @brief  Simple functions for gathering random data
+ *
+ */
+
 #include <stdio.h>
 #include <unistd.h>
 #include <openssl/rand.h>
@@ -29,7 +38,16 @@
 
 static int rand_init = 0;
 
-// Generate some random data and return a string.
+/**
+ * Generate some random data and return a string.  This function makes use of OpenSSL's RAND_pseudo_bytes()
+ * function.
+ *
+ * @param ctx     eurephiaCTX
+ * @param rndstr  Return buffer of the random data
+ * @param len     Size of the return buffer
+ *
+ * @return Returns 1 on success, otherwise 0.
+ */
 int eurephia_randstring(eurephiaCTX *ctx, void *rndstr, size_t len) {
         int attempts = 0;
         do {
diff --git a/common/sha512.c b/common/sha512.c
index 37f4a72..a09a5aa 100644
--- a/common/sha512.c
+++ b/common/sha512.c
@@ -46,6 +46,15 @@
  *   de0ff244877ea60a 4cb0432ce577c31b eb009c5c2c49aa2e 4eadb217ad8cc09b
  */
 
+/**
+ * @file   sha512.c
+ * @author Allan Saddi <allan@saddi.com>
+ * @date   2003-07-25
+ *
+ * @brief  SHA512 hashing functions.
+ *
+ */
+
 #include <stdint.h>
 #include <string.h>