More doxygen comments

2 files changed, 87 insertions, 3 deletions

diff --git a/utils/eurephia_init.c b/utils/eurephia_init.c
index c342617..d47626e 100644
--- a/utils/eurephia_init.c
+++ b/utils/eurephia_init.c
@@ -1,6 +1,6 @@
 /* eurephia_init.c  --  program which initialises the eurephia database.
  *                      It will add a administrator account, setting
- *                      a passoword for it and set other needed
+ *                      a password for it and set other needed
  *                      configuration settings.
  *
  *  GPLv2 only - Copyright (C) 2009
@@ -22,6 +22,15 @@
  *
  */
 
+/**
+ * @file   eurephia_init.c
+ * @author David Sommerseth <dazo@users.sourceforge.net>
+ * @date   2009-03-22
+ *
+ * @brief  A little console based wizard helping configuring new eurephia databases.
+ *
+ */
+
 #include <stdio.h>
 #include <string.h>
 #include <libgen.h>
@@ -82,11 +91,19 @@ void print_help(char *fprg) {
                "  range.  To do this, two limits are defined, the shortest time and the longest time\n"
                "  to be used for calculating a hash.  The default values are 95ms and 200ms.\n"
                "\n"
-               "  If you want to modify those thresolds, you can do so with the --hash-threshold-min\n"
+               "  If you want to modify those thresholds, you can do so with the --hash-threshold-min\n"
                "  and --hash-threshold-max options.  By increasing these numbers, you will allow the\n"
                "  number of rounds to be increased.\n\n");
 }
 
+/**
+ * Establishes a connection to the defined database.  The eurephiaCTX will contain the database connection.
+ *
+ * @param ctx  eurephiaCTX
+ * @param cfg  eurephiaVALUES stack containing the database parameters
+ *
+ * @return Returns 1 on success, otherwise 0.
+ */
 int eurephia_ConnectDB(eurephiaCTX *ctx, eurephiaVALUES *cfg) {
         char *delims = " ";
         char *cp = NULL;
@@ -120,6 +137,13 @@ int eurephia_ConnectDB(eurephiaCTX *ctx, eurephiaVALUES *cfg) {
         return 1;
 }
 
+/**
+ * Guides the user through setting up the first eurephia administrator account.
+ *
+ * @param ctx eurephiaCTX
+ *
+ * @return Returns 1 on success, otherwise 0.
+ */
 int setup_admin_account(eurephiaCTX *ctx) {
         xmlDoc *xmldoc = NULL;
         xmlNode *node = NULL, *node2 = NULL;
@@ -243,6 +267,17 @@ int setup_admin_account(eurephiaCTX *ctx) {
         return 1;
 }
 
+
+/**
+ *  Guides the user through setting up hashing algorithm parameters.  This function will try to find
+ *  the ideal boundaries for hashing rounds, based on how quick the computer can calculate hashes.
+ *
+ * @param ctx eurephiaCTX
+ * @param hash_thr_min Minimum time it should take to calculate a SHA512 hash (in ms)
+ * @param hash_thr_max Maximum time it should take to calculate a SHA512 hash (in ms)
+ *
+ * @return Returns 1 on success, otherwise 0.
+ */
 int setup_password_params(eurephiaCTX *ctx,  const int hash_thr_min, const int hash_thr_max) {
         int rounds_min = 0, rounds_max = 0;
         char buffer[22], prompt[80], value[22];
@@ -293,6 +328,13 @@ int setup_password_params(eurephiaCTX *ctx,  const int hash_thr_min, const int h
 }
 
 
+/**
+ * Guides the user through setting up attempts limits
+ *
+ * @param ctx eurephiaCTX
+ *
+ * @return Returns 1 on success, otherwise 0.
+ */
 int setup_attempt_limits(eurephiaCTX *ctx) {
         char buffer[22], value[22];
         memset(&buffer, 0, 22);
@@ -333,6 +375,14 @@ int setup_attempt_limits(eurephiaCTX *ctx) {
         return 1;
 }
 
+
+/**
+ * Guides the user through setting up session specific parameters, mainly for the admin utilities
+ *
+ * @param ctx eurephiaCTX
+ *
+ * @return Returns 1 on success, otherwise 0.
+ */
 int setup_session_params(eurephiaCTX *ctx) {
         char buffer[20], value[20];
         memset(&buffer, 0, 20);
@@ -354,7 +404,15 @@ int setup_session_params(eurephiaCTX *ctx) {
         return 1;
 }
 
+
 #ifdef FW_IPTABLES
+/**
+ * Guides the user through setting up iptables firewall support, if enabled at compile time.
+ *
+ * @param ctx eurephiaCTX
+ *
+ * @return Returns 1 on success, otherwise 0.
+ */
 int setup_iptables(eurephiaCTX *ctx) {
         char buffer[1026], value[1026], prompt[180];
         memset(&buffer, 0, 1026);
@@ -491,7 +549,7 @@ int main(int argc, char **argv) {
         }
 
         if( eGet_value(cfg, "database_params") == NULL ) {
-                fprintf(stderr, "Missing required database driver parameteres (--database-args)\n");
+                fprintf(stderr, "Missing required database driver parameters (--database-args)\n");
                 return 2;
 
         }
diff --git a/utils/saltdecode.c b/utils/saltdecode.c
index ddaf4c7..c597223 100644
--- a/utils/saltdecode.c
+++ b/utils/saltdecode.c
@@ -19,6 +19,15 @@
  *
  */
 
+/**
+ * @file   saltdecode.c
+ * @author David Sommerseth <dazo@users.sourceforge.net>
+ * @date   2009-03-29
+ *
+ * @brief   Simple utility which decodes a eurephia SHA512 hash salt
+ *
+ */
+
 #include <stdio.h>
 #include <string.h>
 #include <assert.h>
@@ -30,6 +39,14 @@
 #define ROUNDS_MIN 1000
 #define ROUNDS_MAX 999999999
 
+
+/**
+ * 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;
@@ -45,6 +62,15 @@ inline unsigned int get_salt_p2(const char *pwd) {
         return saltinfo_p2;
 }
 
+
+/**
+ * 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;