More comments in common/

19 files changed, 354 insertions, 83 deletions

diff --git a/common/certinfo.c b/common/certinfo.c
index 93766b3..c2601de 100644
--- a/common/certinfo.c
+++ b/common/certinfo.c
@@ -36,7 +36,14 @@
 #include <eurephia_nullsafe.h>
 #include <certinfo.h>
 
-
+/**
+ * Simple strcmp() wrapper, which makes it NULL safe.
+ *
+ * @param s input value
+ * @param v compare value
+ *
+ * @return Returns 1 if s and v are equal, otherwise 0.
+ */
 #define comp_attrib(s, v) ( (v == NULL || strlen_nullsafe(v) < 1) ? 0 : (strcmp(v, s) == 0) )
 
 /**
diff --git a/common/certinfo.h b/common/certinfo.h
index 4f097b8..b180f77 100644
--- a/common/certinfo.h
+++ b/common/certinfo.h
@@ -19,14 +19,26 @@
  *
  */
 
+/**
+ * @file   certinfo.h
+ * @author David Sommerseth <dazo@users.sourceforge.net>
+ * @date   2008-08-06
+ *
+ * @brief  Functions for parsing X.509 subject information
+ *
+ */
+
 #ifndef __CERTINFO_H_
 #define __CERTINFO_H_
 
+/**
+ *  This structure contains certificate information in a structured way.
+ */
 typedef struct _certinfo {
-        char *digest;
-        char *org;
-        char *common_name;
-        char *email;
+        char *digest;		/**< Contains the SHA1 fingerprint (digest) of the certificate */
+        char *org;		/**< Contains the O (organisation) field from the X.509 certificate */
+        char *common_name;	/**< Contains the CN (Common Name) field from the X.509 certificate*/
+        char *email;		/**< Contains the emailAddress field from the X.509 certificate */
 } certinfo;
 
 certinfo *parse_tlsid(const char *);
diff --git a/common/eurephia_admin_struct.h b/common/eurephia_admin_struct.h
index 7d7c591..386d4a9 100644
--- a/common/eurephia_admin_struct.h
+++ b/common/eurephia_admin_struct.h
@@ -19,15 +19,25 @@
  *
 */
 
+/**
+ * @file   eurephia_admin_struct.h
+ * @author David Sommerseth <dsommers@wsdsommers.usersys.redhat.com>
+ * @date   2008-11-28
+ *
+ * @brief  Misc user account flags
+ *
+ */
+
+
 #ifndef EUREPHIA_ADMIN_STRUCT_H
 #define EUREPHIA_ADMIN_STRUCT_H
 
-#define ACCFLAG_NEVERUSED    0x001
-#define ACCFLAG_OPENSESSION  0x002
-#define ACCFLAG_BLACKLISTED  0x004
-#define ACCFLAG_DEACTIVATED  0x008
-#define ACCFLAG_ERRATTEMPT   0x010
-#define ACCFLAG_RSETLASTUSED 0x020
-#define ACCFLAG_RSETLOGINCNT 0x040
+#define ACCFLAG_NEVERUSED    0x001 /**< The user account has never been used */
+#define ACCFLAG_OPENSESSION  0x002 /**< The user is currently logged in, a session is open */
+#define ACCFLAG_BLACKLISTED  0x004 /**< The user account is blacklisted */
+#define ACCFLAG_DEACTIVATED  0x008 /**< The user account is deactivated */
+#define ACCFLAG_ERRATTEMPT   0x010 /**< The user have attempted to login and failed */
+#define ACCFLAG_RSETLASTUSED 0x020 /**< The "last used" time stamp has been reset */
+#define ACCFLAG_RSETLOGINCNT 0x040 /**< The "login count" has been reset */
 
 #endif
diff --git a/common/eurephia_context.h b/common/eurephia_context.h
index 1ec637d..877632c 100644
--- a/common/eurephia_context.h
+++ b/common/eurephia_context.h
@@ -28,14 +28,15 @@
  *
  */
 
-/*** Structures used by the eurephia module  ***/
-
 #ifndef   	EUREPHIASTRUCT_H_
 #define   	EUREPHIASTRUCT_H_
 
 #include <stdio.h>
 #include "eurephiadb_struct.h"
 
+/**
+ *  eurephia context types
+ */
 #define ECTX_NO_PRIVILEGES 0x1000 /**< The context should not have any privileges at all */
 #define ECTX_PLUGIN_AUTH   0x1001 /**< The context is used in a openvpn plug-in setting */
 #define ECTX_ADMIN_CONSOLE 0x2001 /**< The context is used via the eurephiadm console utility */
diff --git a/common/eurephia_directions.h b/common/eurephia_directions.h
index 5eccf46..fa2adba 100644
--- a/common/eurephia_directions.h
+++ b/common/eurephia_directions.h
@@ -19,11 +19,32 @@
  *
  */
 
+/**
+ * @file   eurephia_directions.h
+ * @author David Sommerseth <dazo@users.sourceforge.net>
+ * @date   2008-08-06
+ *
+ * @brief  Macro to decide the best search directon on dual-way
+ *         ring based pointer chains
+ *
+ */
+
 #ifndef _EUREPHIA_DIRECTIONS_H
 #define _EUREPHIA_DIRECTIONS_H
 
-#define DIR_R 'R'
-#define DIR_L 'L'
+#define DIR_R 'R'		/**< "Right" direction, where the ID number increases (next element)    */
+#define DIR_L 'L'		/**< "Left" direction, where the ID number decreases (previous element) */
+
+/**
+ * This macro finds the quickest way to go from one element to another one in
+ * a circular dual-way pointer chain, based on a numeric id of the elements.
+ *
+ * @param s starting point on the chain
+ * @param d destination point on the chain
+ * @param l number of elements in the chain
+ *
+ * @return Returns DIR_R or DIR_L, depending on what will be the shortest distance.
+ */
 #define DIRECTION(s,d,l) (s>d ? ((((l-s)+d) > (s-d)) ? DIR_L : DIR_R) : (((d-s) > ((l-d)+s)) ? DIR_L : DIR_R))
 
 #endif
diff --git a/common/eurephia_getsym.h b/common/eurephia_getsym.h
index ed16dcc..b2c8f60 100644
--- a/common/eurephia_getsym.h
+++ b/common/eurephia_getsym.h
@@ -19,9 +19,18 @@
  *
  */
 
+/**
+ * @file   eurephia_getsym.h
+ * @author David Sommerseth <dazo@users.sourceforge.net>
+ * @date   2008-08-10
+ *
+ * @brief  Helper functions for handling dynamic loaded objects (.so files)
+ *
+ */
+
 #ifndef   	EUREPHIA_GETSYM_H_
 #define   	EUREPHIA_GETSYM_H_
 
-void *eGetSym(eurephiaCTX *ctx, const void *dlh, const char *symnam) ;
+void *eGetSym(eurephiaCTX *ctx, void *dlh, const char *symnam);
 
 #endif 	    /* !EUREPHIA_GETSYM_H_ */
diff --git a/common/eurephia_log.c b/common/eurephia_log.c
index 76dff8c..0955aa0 100644
--- a/common/eurephia_log.c
+++ b/common/eurephia_log.c
@@ -38,22 +38,27 @@
 #include <eurephia_context.h>
 #include "eurephia_log.h"
 
+/**
+ * Mapping table for mapping log types (defined in eurephia_log.h)
+ * to string values
+ */
 const char *erp_logtypes[] = {
         "\0",
-        "-- INFO --      \0",
-        "-- DEBUG --     \0",
-        "** WARNING **   \0",
-        "** ERROR **     \0",
-        "** CRITICAL **  \0",
-        "** - FATAL - ** \0",
-        "** * PANIC * ** \0"
+        "-- INFO --      \0",	/**< LOG_INFO     */
+        "-- DEBUG --     \0",	/**< LOG_DEBUG    */
+        "** WARNING **   \0",	/**< LOG_WARNING  */
+        "** ERROR **     \0",	/**< LOG_ERROR    */
+        "** CRITICAL **  \0",	/**< LOG_CRITICAL */
+        "** - FATAL - ** \0",	/**< LOG_FATAL    */
+        "** * PANIC * ** \0"	/**< LOG_PANIC    */
 };
 
-// POSIX Mutex to avoid simultaneously logging activity from
-// several threads at the same time
+/**
+ * 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
  *
diff --git a/common/eurephia_log.h b/common/eurephia_log.h
index 647c557..97e58d2 100644
--- a/common/eurephia_log.h
+++ b/common/eurephia_log.h
@@ -19,22 +19,36 @@
  *
  */
 
+/**
+ * @file   eurephia_log.h
+ * @author David Sommerseth <dazo@users.sourceforge.net>
+ * @date   2008-08-06
+ *
+ * @brief  Function for unified logging
+ *
+ */
+
 #ifndef   	EUREPHIA_LOG_H_
 #define   	EUREPHIA_LOG_H_
 
 #include <eurephia_context.h>
 
-#define LOG_INFO  1
-#define LOG_DEBUG 2
-#define LOG_WARNING 3
-#define LOG_ERROR 4
-#define LOG_CRITICAL 5
-#define LOG_FATAL 6
-#define LOG_PANIC 7
+#define LOG_INFO  1		/**< Informational messages. Log level should be < 5 */
+#define LOG_DEBUG 2		/**< Messages intended when debugging. Only for log level > 10 */
+#define LOG_WARNING 3		/**< Input data or processing revealed unexpected data. Log level never > 2*/
+#define LOG_ERROR 4		/**< API errors but not sever, program can continue to run */
+#define LOG_CRITICAL 5		/**< Operation failed and might have been aborted.  Log level always 0 */
+#define LOG_FATAL 6             /**< Operation failed and cannot continue. Log level always < 2 */
+#define LOG_PANIC 7		/**< Action failed an program could not continue to run. Log level always 0 */
 
 #ifdef ENABLE_DEBUG
 #warning ######   DEBUG LOGGING IS ENABLED - THIS COULD BE A SECURITY ISSUE   ######
-#define DEBUG(ctx, lvl, rest...) eurephia_log(ctx, LOG_DEBUG, lvl, ## rest);
+/**
+ *  Wrapper function for DEBUG statements.  This is used to avoid adding debug code into the compiled
+ *  binary if debug logging is not enabled at compile time.  This will always use the LOG_DEBUG target
+ *  when calling eurephia_log().
+ */
+#define DEBUG(ctx, log_level, log_string...) eurephia_log(ctx, LOG_DEBUG, log_level, ## log_string);
 #else
 #define DEBUG(ctx, lvl, rest...) {};
 #endif
diff --git a/common/eurephia_nullsafe.h b/common/eurephia_nullsafe.h
index 531d6f2..55a9148 100644
--- a/common/eurephia_nullsafe.h
+++ b/common/eurephia_nullsafe.h
@@ -20,15 +20,81 @@
  *  along with this program; if not, write to the Free Software
  *  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
  *
-*/
+ */
+
+/**
+ * @file   eurephia_nullsafe.h
+ * @author David Sommerseth <dazo@users.sourceforge.net>
+ * @date   2008-08-06
+ *
+ * @brief standard C string functions, which is made NULL safe by checking
+ *        if input value is NULL before performing the action.
+ *
+ */
 
 #ifndef   	EUREPHIA_NULLSAFE_H_
 #define    	EUREPHIA_NULLSAFE_H_
 
+/**
+ * atoi() wrapper.  Converts any string into a integer
+ *
+ * @param str Input string
+ *
+ * @return Returns integer
+ */
 #define atoi_nullsafe(str) (str != NULL ? atoi(str) : 0)
+
+
+/**
+ * strdup() wrapper.  Duplicates the input string.
+ *
+ * @param str Input string to be duplicated
+ *
+ * @return Returns a pointer to the duplicate (char *) on success, NULL otherwise.
+ * If input was NULL, NULL is returned.
+ */
 #define strdup_nullsafe(str) (str != NULL ? strdup(str) : NULL)
+
+
+/**
+ * strlen() wrapper.  Returns the length of a string
+ *
+ * @param str Input string
+ *
+ * @return Returns int with length of string.  If input is NULL, it returns 0.
+ */
 #define strlen_nullsafe(str) (str != NULL ? strlen(str) : 0)
-#define free_nullsafe(str) if( str != NULL ) { free(str); str = NULL;}
+
+
+/**
+ * free() wrapper.  Frees memory allocated by malloc() or calloc().  It also sets the
+ * input pointer to NULL on success.
+ *
+ * @param ptr Pointer to the memory region being freed.
+ *
+ */
+#define free_nullsafe(ptr) if( ptr != NULL ) { free(ptr); ptr = NULL; }
+
+
+/**
+ * Function which will return a default string value if no input data was provided.
+ *
+ * @param str     Input string
+ * @param defstr  Default string
+ *
+ * @return Returns the pointer to the input string if the string length > 0.  Otherwise it
+ * will return a pointer to the default string.
+ */
 #define defaultValue(str, defstr) (strlen_nullsafe(str) == 0 ? defstr : str)
+
+
+/**
+ * Function which will return a default integer value if no input data was provided.
+ *
+ * @param ival   input integer value
+ * @param defval default integer value
+ *
+ * @return Returns the ival value if it is > 0, otherwise defval value is returned.
+ */
 #define defaultIntValue(ival, defval) (ival == 0 ? defval : ival)
 #endif 	    /* !EUREPHIA_NULLSAFE_H_ */
diff --git a/common/eurephia_values.h b/common/eurephia_values.h
index a44312f..dcb81bc 100644
--- a/common/eurephia_values.h
+++ b/common/eurephia_values.h
@@ -19,6 +19,15 @@
  *
  */
 
+/**
+ * @file   eurephia_values.h
+ * @author David Sommerseth <dazo@users.sourceforge.net>
+ * @date   2008-08-06
+ *
+ * @brief  Generic interface for handling key->value pairs
+ *
+ */
+
 #ifndef   	EUREPHIA_VALUES_H_
 # define   	EUREPHIA_VALUES_H_
 
@@ -32,6 +41,14 @@ eurephiaVALUES *eCreate_value_space(eurephiaCTX *ctx, int evid);
 void eAdd_valuestruct(eurephiaCTX *ctx, eurephiaVALUES *vls, eurephiaVALUES *newval);
 void eAdd_value(eurephiaCTX *ctx, eurephiaVALUES *vls, const char *key, const char *val);
 
+/**
+ * Front-end function for eFree_values_func().  Frees eurephiaVALUES pointer chain and
+ * sets the pointer to NULL.
+ *
+ * @param c eurephiaCTX
+ * @param v eurephiaVALUES pointer which is being freed.
+ *
+ */
 #define eFree_values(c, v) { eFree_values_func(c, v); v = NULL; }
 void eFree_values_func(eurephiaCTX *ctx, eurephiaVALUES *vls);
 
diff --git a/common/eurephia_values_struct.h b/common/eurephia_values_struct.h
index 37e709e..69b3c02 100644
--- a/common/eurephia_values_struct.h
+++ b/common/eurephia_values_struct.h
@@ -19,15 +19,30 @@
  *
  */
 
+/**
+ * @file   eurephia_values_struct.h
+ * @author David Sommerseth <dazo@users.sourceforge.net>
+ * @date   2008-11-05
+ *
+ * @brief  Definition of the eurephiaVALUES struct
+ *
+ */
+
 #ifndef   	EUREPHIA_VALUES_STRUCT_H_
 # define   	EUREPHIA_VALUES_STRUCT_H_
 
+/**
+ * eurephiaVALUES is a pointer chain with key/value pairs.  If having several
+ * such pointer chains, they can be given different group IDs to separate them,
+ * especially during debugging.
+ *
+ */
 typedef struct __eurephiaVALUES {
-        unsigned int evgid;
-        unsigned int evid;
-        char *key;
-        char *val;
-        struct __eurephiaVALUES *next;
+        unsigned int evgid;	/**< Group ID, all elements in the same chain should have the same value */
+        unsigned int evid;	/**< Unique ID per element in a pointer chain */
+        char *key;		/**< The key name of a value */
+        char *val;		/**< The value itself */
+        struct __eurephiaVALUES *next; /**< Pointer to the next element in the chain. NULL == end of chain */
 } eurephiaVALUES;
 
 #endif 	    /* !EUREPHIA_VALUES_STRUCT_H_ */
diff --git a/common/eurephia_xml.h b/common/eurephia_xml.h
index 57b9073..cfa0e60 100644
--- a/common/eurephia_xml.h
+++ b/common/eurephia_xml.h
@@ -19,10 +19,25 @@
  *
  */
 
+/**
+ * @file   eurephia_xml.h
+ * @author David Sommerseth <dazo@users.sourceforge.net>
+ * @date   2008-12-15
+ *
+ * @brief  Generic XML parser functions
+ *
+ */
+
+
 #ifndef   	EUREPHIA_XML_H_
 # define   	EUREPHIA_XML_H_
 
-typedef enum _exmlResultType { exmlRESULT = 1, exmlERROR } exmlResultType;
+/**
+ * Result types used by eurephiaXML_ResultMsg()
+ */
+typedef enum _exmlResultType { exmlRESULT = 1, /**< Operation successful. Additional info might be available*/
+			       exmlERROR       /**< Operation failed. Error message must be enclosed */
+} exmlResultType;
 
 #include <stdarg.h>
 
diff --git a/common/eurephiadb_session_common.c b/common/eurephiadb_session_common.c
index 8c18ceb..a810bf0 100644
--- a/common/eurephiadb_session_common.c
+++ b/common/eurephiadb_session_common.c
@@ -42,12 +42,12 @@
 
 
 #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
+// Function needed to be found in the database driver
 int (*eDBstore_session_value) (eurephiaCTX *ctx, eurephiaSESSION *session, int mode,
                                const char *key, const char *val);
 #else
 int eDBstore_session_value (eurephiaCTX *ctx, eurephiaSESSION *session, int mode,
-                               const char *key, const char *val);
+			    const char *key, const char *val);
 #endif
 
 /**
diff --git a/common/eurephiadb_session_common.h b/common/eurephiadb_session_common.h
index 035e313..ebe0a75 100644
--- a/common/eurephiadb_session_common.h
+++ b/common/eurephiadb_session_common.h
@@ -19,14 +19,40 @@
  *
  */
 
+/**
+ * @file   eurephiadb_session_common.h
+ * @author David Sommerseth <dazo@users.sourceforge.net>
+ * @date   2008-11-28
+ *
+ * @brief  Common functions for handling eurephia sessions.
+ *
+ */
+
 #ifndef   	EUREPHIADB_SESSION_COMMON_H_
 #define   	EUREPHIADB_SESSION_COMMON_H_
 
 #include <eurephia_values.h>
 
 int eDBset_session_value(eurephiaCTX *ctx, eurephiaSESSION *session, const char *key, const char *val);
+
+/**
+ * Wrapper function for retrieving a value from a session variable
+ *
+ * @param s eurephiaSESSION pointer
+ * @param k key of the value to look for
+ *
+ * @return Returns a string (char *) containing the value of the key, or NULL on failure.
+ */
 #define eDBget_session_value(s, k) eGet_value(s->sessvals, k);
 
+
+/**
+ * Front-end function for eDBfree_session_func().  Frees the memory used by an eurephiaSESSION struct
+ * and sets the freed pointer to NULL
+ *
+ * @param c eurephiaCTX
+ * @param s eurephiaSESSION pointer which is being freed.
+ */
 #define eDBfree_session(c, s) { eDBfree_session_func(c, s); s = NULL; }
 void eDBfree_session_func(eurephiaCTX *ctx, eurephiaSESSION *sk);
 
diff --git a/common/eurephiadb_session_struct.h b/common/eurephiadb_session_struct.h
index 8cd9657..93ea5e9 100644
--- a/common/eurephiadb_session_struct.h
+++ b/common/eurephiadb_session_struct.h
@@ -19,29 +19,44 @@
  *
  */
 
+/**
+ * @file   eurephiadb_session_struct.h
+ * @author David Sommerseth <dazo@users.sourceforge.net>
+ * @date   2008-11-05
+ *
+ * @brief  Definition of eurephiaSESSION struct and other
+ *         session oriented constants
+ *
+ */
+
 #ifndef   	EUREPHIADB_SESSION_STRUCT_H_
 #define   	EUREPHIADB_SESSION_STRUCT_H_
 
-typedef enum { stAUTHENTICATION, stSESSION} sessionType;
+/**
+ * Defines the different session types available
+ */
+typedef enum { stAUTHENTICATION, /**< A pure authentication session, should only be used during auth. */
+	       stSESSION	 /**< A user session, may contain variables related to users session */
+} sessionType;
 
-#define SESSION_NEW        1
-#define SESSION_EXISTING   2
-#define SESSION_REGISTERED 3
-#define SESSION_LOGGEDOUT  4
+#define SESSION_NEW        1	/**< The session is newly created */
+#define SESSION_EXISTING   2	/**< The session is reloaded from a previously saved session */
+#define SESSION_REGISTERED 3	/**< The session is registered as logged in */
+#define SESSION_LOGGEDOUT  4	/**< The user logged out and the session is closed */
 
-#define SESSVAL_NEW      10
-#define SESSVAL_UPDATE   11
-#define SESSVAL_DELETE   12
+#define SESSVAL_NEW      10	/**< Save a new session value in the database */
+#define SESSVAL_UPDATE   11	/**< Update an existing session value in the database */
+#define SESSVAL_DELETE   12	/**< Delete a session value */
 
-//
-// Struct which contains session unique data
-//
+/**
+ * Struct which contains session unique data
+ */
 typedef struct {
-        char *sessionkey;
-        int sessionstatus;
-        sessionType type;
-        eurephiaVALUES *sessvals;
+        char *sessionkey;	/**< A unique session key. */
+        int sessionstatus;	/**< Must be SESSION_NEW, SESSION_EXISTING,
+				  *  SESSION_REGISTERED or SESSION_LOGGEDOUT */
+        sessionType type;	/**< Must be stAUTHENTICATION or stSESSION */
+        eurephiaVALUES *sessvals; /**< Values unique for this session only */
 } eurephiaSESSION;
 
-
 #endif 	    /* !EUREPHIADB_SESSION_STRUCT_H_ */
diff --git a/common/passwd.c b/common/passwd.c
index 70fc3d3..3a887c7 100644
--- a/common/passwd.c
+++ b/common/passwd.c
@@ -63,18 +63,17 @@
 #include "passwd.h"
 #include "sha512.h"
 
+#define DEFAULT_SALT_LEN 32	/**< Default hash salt length */
+#define MAX_SALT_LEN 255	/**< Maximum hash salt length */
 
-// default and maximum allowed salt length
-#define DEFAULT_SALT_LEN 32
-#define MAX_SALT_LEN 255
-// When randomising rounds, this is the default scope
-#define ROUNDS_DEFAULT_MIN 5000
-#define ROUNDS_DEFAULT_MAX 7500
-// Min/Max rounds boundaries
-#define ROUNDS_MIN 1000
-#define ROUNDS_MAX 999999999
-
-/* Table with characters for base64 transformation.  */
+#define ROUNDS_DEFAULT_MIN 5000 /**< Default minimum hashing rounds (may be changed in runtime config)*/
+#define ROUNDS_DEFAULT_MAX 7500 /**< Default maximum hashing rounds (may be changed in runtime config)*/
+#define ROUNDS_MIN 1000		/**< Absolutely minimum hashing rounds */
+#define ROUNDS_MAX 999999999	/**< Absolutely maximum hashing rounds */
+
+/**
+ *Table with characters for base64 transformation.
+*/
 static const char b64t[64] =
 "./0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
 
@@ -179,6 +178,26 @@ int gen_randsaltstr(eurephiaCTX *ctx, char *saltstr, int len) {
 
 
 /**
+ *  Internal function used by sha512_crytp_r().  Converts 24 bits of data into base64 format.
+ *
+ * @param B2
+ * @param B1
+ * @param B0
+ * @param N
+ */
+#define b64_from_24bit(B2, B1, B0, N)					\
+        do {                                                            \
+                unsigned int w = ((B2) << 16) | ((B1) << 8) | (B0);     \
+                int n = (N);                                            \
+                while (n-- > 0 && buflen > 0) {                         \
+                        *cp++ = b64t[w & 0x3f];                         \
+                        --buflen;                                       \
+                        w >>= 6;                                        \
+                }                                                       \
+        } while (0)
+
+
+/**
  * Internal SHA512 hashing function.  Does the real hashing job
  *
  * @param key            The password of the user
@@ -370,17 +389,6 @@ inline char *sha512_crypt_r(const char *key, const char *salt, size_t maxrounds_
         cp = __stpncpy (buffer, salt, MIN ((size_t) MAX (0, buflen), salt_len));
         buflen -= MIN ((size_t) MAX (0, buflen), salt_len);
 
-#define b64_from_24bit(B2, B1, B0, N)                                   \
-        do {                                                            \
-                unsigned int w = ((B2) << 16) | ((B1) << 8) | (B0);     \
-                int n = (N);                                            \
-                while (n-- > 0 && buflen > 0) {                         \
-                        *cp++ = b64t[w & 0x3f];                         \
-                        --buflen;                                       \
-                        w >>= 6;                                        \
-                }                                                       \
-        } while (0)
-
         b64_from_24bit (alt_result[0],  alt_result[21], alt_result[42], 4);
         b64_from_24bit (alt_result[22], alt_result[43], alt_result[1],  4);
         b64_from_24bit (alt_result[44], alt_result[2],  alt_result[23], 4);
diff --git a/common/passwd.h b/common/passwd.h
index ba4a39d..004a803 100644
--- a/common/passwd.h
+++ b/common/passwd.h
@@ -19,6 +19,15 @@
  *
  */
 
+/**
+ * @file   passwd.h
+ * @author David Sommerseth <dazo@users.sourceforge.net>
+ * @date   2009-03-21
+ *
+ * @brief  Functions for generating SHA512 hashes from clear-text values.
+ *
+ */
+
 #ifndef PASSWD_H
 #define PASSWD_H
 
diff --git a/common/randstr.h b/common/randstr.h
index f8bfcd4..cc04f18 100644
--- a/common/randstr.h
+++ b/common/randstr.h
@@ -19,6 +19,15 @@
  *
  */
 
+/**
+ * @file   randstr.h
+ * @author David Sommerseth <dazo@users.sourceforge.net>
+ * @date   2009-01-10
+ *
+ * @brief  Simple functions for gathering random data
+ *
+ */
+
 #ifndef   	RANDSTR_H_
 #define   	RANDSTR_H_
 
diff --git a/common/sha512.h b/common/sha512.h
index a6962c2..5639790 100644
--- a/common/sha512.h
+++ b/common/sha512.h
@@ -32,6 +32,15 @@
  * $Id: sha512.h 350 2003-02-23 22:12:33Z asaddi $
  */
 
+/**
+ * @file   sha512.h
+ * @author Allan Saddi <allan@saddi.com>
+ * @date   2003-07-25
+ *
+ * @brief  SHA512 hashing functions.
+ *
+ */
+
 #ifndef _SHA512_H
 #define _SHA512_H
 
@@ -42,6 +51,9 @@
 /* Hash size in 64-bit words */
 #define SHA512_HASH_WORDS 8
 
+/**
+ * SHA512 context, used during creating the SHA512 hash
+ */
 struct _SHA512Context {
   uint64_t totalLength[2];
   uint64_t hash[SHA512_HASH_WORDS];