Added doxygen comments

3 files changed, 148 insertions, 6 deletions

diff --git a/plugin/firewall/eurephiafw.c b/plugin/firewall/eurephiafw.c
index e57f7cc..0ee83de 100644
--- a/plugin/firewall/eurephiafw.c
+++ b/plugin/firewall/eurephiafw.c
@@ -19,6 +19,16 @@
  *
  */
 
+/**
+ * @file   eurephiafw.c
+ * @author David Sommerseth <dazo@users.sourceforge.net>
+ * @date   2008-08-10
+ *
+ * @brief  Takes care of loading the configured firewall driver and provides a
+ *         generic API for updating the firewall rules.
+ *
+ */
+
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
@@ -41,6 +51,14 @@
 #include "eurephiafw_helpers.h"
 #include "eurephiadb_driver.h"
 
+
+/**
+ * Unloads the firewall driver
+ *
+ * @param ctx eurephiaCTX
+ *
+ * @return Returns 1 on success, otherwise 0.
+ */
 int eFW_unload(eurephiaCTX *ctx) {
         if( ctx == NULL ) {
                 return 1;
@@ -56,6 +74,14 @@ int eFW_unload(eurephiaCTX *ctx) {
 }
 
 
+/**
+ * Loads the given firewall driver/interface
+ *
+ * @param ctx   eurephiaCTX
+ * @param intf  full path to the firewall interface
+ *
+ * @return Returns 1 on success, otherwise 0.
+ */
 int eFW_load(eurephiaCTX *ctx, const char *intf) {
         if( (intf == NULL) || (strlen(intf) == 0) ) {
                 eurephia_log(ctx, LOG_FATAL, 0, "No valid eurephia firewall interface indicated");
@@ -82,7 +108,7 @@ int eFW_load(eurephiaCTX *ctx, const char *intf) {
         default:
                 eurephia_log(ctx, LOG_WARNING, 0,
                              "eurephia Firewall interface API is newer than what the running eurephia version is "
-                             "familiar with.  Please consider to upgrade eurphia to take advantage of newer "
+                             "familiar with.  Please consider to upgrade eurephia to take advantage of newer "
                              "features in the eurephiaDB driver.");
 
         case 1:
@@ -100,6 +126,13 @@ int eFW_load(eurephiaCTX *ctx, const char *intf) {
         return 1;
 }
 
+
+/**
+ * Starts the firewall thread.  It is started as a separate process, to make sure it will run with
+ * root privileges.
+ *
+ * @param ctx  eurephiaCTX
+ */
 void eFW_StartFirewall(eurephiaCTX *ctx) {
         struct mq_attr mqattr;
         eurephiaCTX *shadowctx = NULL;
@@ -250,6 +283,12 @@ void eFW_StartFirewall(eurephiaCTX *ctx) {
         }
 }
 
+
+/**
+ * Stops the firewall update process.
+ *
+ * @param ctx  eurephiaCTX
+ */
 void eFW_StopFirewall(eurephiaCTX *ctx) {
         char buf[520], *fwdest = NULL;
         struct timespec tsp;
@@ -289,7 +328,7 @@ void eFW_StopFirewall(eurephiaCTX *ctx) {
         // Wait for the firewall module process to finish
         //
 
-        // prepare a timeout - 30 secounds should be enough
+        // prepare a timeout - 30 seconder's should be enough
         if( clock_gettime(CLOCK_REALTIME, &tsp) == -1 ) {
                 eurephia_log(ctx, LOG_FATAL, 0, "Could not prepare timeout for firewall shutdown: %s",
                              strerror(errno));
@@ -318,6 +357,17 @@ void eFW_StopFirewall(eurephiaCTX *ctx) {
 }
 
 
+/**
+ * Requests an update of the firewall rules
+ *
+ * @param ctx        eurephiaCTX
+ * @param mode       int value which can be FWRULE_ADD, FWRULE_DELETE, FWRULE_BLACKLIST
+ * @param addr       The address of the rule to be changed (IP address or MAC address)
+ * @param fwdest     The firewall destination, where the rule is (to be) found.
+ * @param fwprofile  The firewall profile the user is defined to make use of.
+ *
+ * @return Returns 1 on success, otherwise 0.
+ */
 int eFW_UpdateFirewall(eurephiaCTX *ctx, int mode,
                        const char *addr, const char *fwdest, const char *fwprofile) {
         char buf[1026];
diff --git a/plugin/firewall/eurephiafw_helpers.c b/plugin/firewall/eurephiafw_helpers.c
index 7ea549b..76ff9cd 100644
--- a/plugin/firewall/eurephiafw_helpers.c
+++ b/plugin/firewall/eurephiafw_helpers.c
@@ -1,5 +1,5 @@
 /* eurephiafw_helpers.c  --  Helper functions, shared between main module and
- *                           firewall module.  Setting up Posix MQ and semaphores
+ *                           firewall module.  Setting up POSIX MQ and semaphores
  *
  *  GPLv2 only - Copyright (C) 2008, 2009
  *               David Sommerseth <dazo@users.sourceforge.net>
@@ -20,6 +20,16 @@
  *
  */
 
+/**
+ * @file   eurephiafw_helpers.c
+ * @author David Sommerseth <dazo@users.sourceforge.net>
+ * @date   2009-08-14
+ *
+ * @brief  Helper functions which is shared between the main eurephia-auth module and
+ *         the firewall module.  It takes care of preparing POSIX MQ queues and semaphores.
+ *
+ */
+
 #include <stdio.h>
 #include <string.h>
 #include <errno.h>
@@ -34,7 +44,15 @@
 #include "eurephiafw.h"
 #include "eurephiafw_helpers.h"
 
-
+/**
+ * Prepares the POSIX Semaphores used to control the communication between the openvpn process
+ * and the firewall updater process.
+ *
+ * @param ctx eurephiaCTX
+ * @param cfg efw_threaddata, data used in the firewall process and contains pointers to the semaphores.
+ *
+ * @return Returns 1 on success, otherwise 0.
+ */
 int efwSetupSemaphores(eurephiaCTX *ctx, efw_threaddata *cfg) {
         // Initialise the main process' semaphore
         cfg->semp_master = sem_open(SEMPH_MASTER, O_CREAT, 0666, 0);
@@ -52,6 +70,15 @@ int efwSetupSemaphores(eurephiaCTX *ctx, efw_threaddata *cfg) {
         return 1;
 }
 
+
+/**
+ * Removes the semaphores created by efwSetupSemaphores().
+ *
+ * @param ctx eurephiaCTX
+ * @param cfg efw_threaddata, data used in the firewall process and contains pointers to the semaphores.
+ *
+ * @return Returns 1 on success, otherwise 0.
+ */
 int efwRemoveSemaphores(eurephiaCTX *ctx, efw_threaddata *cfg) {
         if( sem_close(cfg->semp_worker) != 0 ) {
                 eurephia_log(ctx, LOG_WARNING, 0,
@@ -67,6 +94,15 @@ int efwRemoveSemaphores(eurephiaCTX *ctx, efw_threaddata *cfg) {
         return 1;
 }
 
+
+/**
+ * Creates the needed POSIX MQ message queues.
+ *
+ * @param ctx eurephiaCTX
+ * @param cfg efw_threaddata, data used in the firewall process and contains pointers to the MQ fd.
+ *
+ * @return Returns 1 on success, otherwise 0.
+ */
 int efwSetupMessageQueue(eurephiaCTX *ctx, efw_threaddata *cfg) {
         struct mq_attr mqattr;
 
@@ -82,6 +118,15 @@ int efwSetupMessageQueue(eurephiaCTX *ctx, efw_threaddata *cfg) {
         return 1;
 }
 
+
+/**
+ * Removes the POSIX MQ message queues created by efwSetupMessageQueue()
+ *
+ * @param ctx eurephiaCTX
+ * @param cfg efw_threaddata, data used in the firewall process and contains pointers to the MQ fd.
+ *
+ * @return Returns 1 on success, otherwise 0.
+ */
 int efwRemoveMessageQueue(eurephiaCTX *ctx, efw_threaddata *cfg) {
         // Close and remove the message queue used
         if( mq_close((*cfg).msgq) != 0 ) {
@@ -95,4 +140,3 @@ int efwRemoveMessageQueue(eurephiaCTX *ctx, efw_threaddata *cfg) {
         }
         return 1;
 }
-
diff --git a/plugin/firewall/iptables/efw-iptables.c b/plugin/firewall/iptables/efw-iptables.c
index ea82e04..b686ca9 100644
--- a/plugin/firewall/iptables/efw-iptables.c
+++ b/plugin/firewall/iptables/efw-iptables.c
@@ -19,6 +19,16 @@
  *
  */
 
+/**
+ * @file   efw-iptables.c
+ * @author David Sommerseth <dazo@users.sourceforge.net>
+ * @date   2008-08-10
+ *
+ * @brief  Firewall driver for iptables.  Understands how to update iptables, in other words.
+ *
+ */
+
+
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
@@ -37,11 +47,21 @@
 #define INTERFACEVER "1.0"
 #define INTERFACEAPIVER 1
 
-
+/**
+ * Mandatory function, contains driver information.
+ *
+ * @return Retuns a static string, containing the version information.
+ */
 const char *eFWinterfaceVersion() {
         return "eFW-iptables (v"INTERFACEVER")  David Sommerseth 2008 (C) GPLv2";
 }
 
+
+/**
+ * Mandatory function, contains driver information.
+ *
+ * @return Retuns an integer which correponds to the API level this driver corresponds to.
+ */
 int eFWinterfaceAPIversion() {
         return INTERFACEAPIVER;
 }
@@ -50,6 +70,12 @@ int eFWinterfaceAPIversion() {
 int process_input(eurephiaCTX *ctx, const char *fwcmd, const char *msg);
 int call_iptables(eurephiaCTX *ctx, const char *fwcmd, char **ipt_args);
 
+
+/**
+ * The main routine of the firewall interface.  This loops until it gets a shutdown message.
+ *
+ * @param fwargs efw_threaddata pointer, with needed information to communicate with the openvpn process.
+ */
 void eFW_RunFirewall(void *fwargs) {
         efw_threaddata *cfg = (efw_threaddata *) fwargs;
         eurephiaCTX *ctx = (eurephiaCTX *) cfg->ctx;
@@ -124,6 +150,16 @@ void eFW_RunFirewall(void *fwargs) {
 }
 
 
+/**
+ * Internal function.  Processes firewall update messages recieved via POSIX MQ.
+ *
+ * @param ctx    eurephiaCTX - This is just a shadow context, to make logging possible
+ * @param fwcmd  The command to be executed, can be 'A'-add, 'D'-delete, 'F'-flush, 'B'-blacklist, 'I'-init
+ * @param input  Contains a string with information for the command.  Format varies with command mode.
+ *
+ * @return Returns 1 on success, otherwise 0.  If 0 is sent, it means the firewall process should shut down,
+ *         and it should only be used in very critical situations.
+ */
 int process_input(eurephiaCTX *ctx, const char *fwcmd, const char *input) {
         char mode[3], *addr = NULL, *destchain = NULL, *jump = NULL;
         char *msg = NULL, *orig_msg = NULL;
@@ -271,6 +307,18 @@ int process_input(eurephiaCTX *ctx, const char *fwcmd, const char *input) {
 	return ret;
 }
 
+
+/**
+ * This function does the actual iptables call.  It will fork out a process and do the
+ * assigned iptables command.
+ *
+ * @param ctx      eurephiaCTX - shadow context, only with pointers to log files.
+ * @param fwcmd    String containing full filename to the binary to execute
+ * @param ipt_args The iptables arguments
+ *
+ * @return Returns 1 on success, otherwise 0.  When 0 is returned, the complete firewall process will be 
+ *         shut down.
+ */
 int call_iptables(eurephiaCTX *ctx, const char *fwcmd, char **ipt_args) {
         pid_t pid;
         int cmdret = -1;