Added doxygen comments

6 files changed, 330 insertions, 30 deletions

diff --git a/plugin/eurephia-auth.c b/plugin/eurephia-auth.c
index acccf18..ef4f8c4 100644
--- a/plugin/eurephia-auth.c
+++ b/plugin/eurephia-auth.c
@@ -1,4 +1,4 @@
-/* eurephia-auth.c  --  Main OpenVPN plugin functions.
+/* eurephia-auth.c  --  Main OpenVPN plug-in functions.
  *                      The API level between OpenVPN and eurephia-auth
  *
  *  GPLv2 only - Copyright (C) 2008, 2009
@@ -20,6 +20,15 @@
  *
  */
 
+/**
+ * @file   eurephia-auth.c
+ * @author David Sommerseth <dazo@users.sourceforge.net>
+ * @date   2008-08-06
+ *
+ * @brief  Implements the API which the OpenVPN plug-in interface requires
+ *
+ */
+
 #include <stdio.h>
 #include <unistd.h>
 
@@ -59,6 +68,16 @@ static const char *plugin_type_name(const int type)
     }
 }
 
+
+/**
+ * Dumps the contents of the environmental table to the given FILE.  This function is only available 
+ * if DEBUG is defined during compilation.  If SHOW_SECRETS is not defined, it will mask the contents
+ * of the password field, if found.
+ *
+ * @param f       FILE * where the contents will be dumped
+ * @param prefix  Adds a fixed prefix to each of the lines
+ * @param envp    openvpn environmental table
+ */
 static void dump_env(FILE *f, const char *prefix, const char *envp[]) {
         int i;
         for (i = 0; envp[i]; i++) {
@@ -73,10 +92,13 @@ static void dump_env(FILE *f, const char *prefix, const char *envp[]) {
 #endif // ENABLE_DEBUG
 
 
-// daemonize if "daemon" environment variable is set.
-// preserves stderr access after being daemonized, but
-// only if "daemon_log_direct" enviroment variable is set.
-//
+/**
+ * daemonize if "daemon" environment variable is set.
+ * preserves stderr access after being daemonized, but
+ * only if "daemon_log_direct" environment variable is set.
+ *
+ * @param envp openvpn environmental table
+ */
 static void daemonize(const char *envp[])
 {
         const char *daemon_string = get_env(NULL, 0, envp, "daemon");
@@ -96,6 +118,16 @@ static void daemonize(const char *envp[])
 }
 
 
+/**
+ * Prepares a eurephiaCTX (context) for the openvpn process and tells openvpn which hooks eurephia
+ * will make use of.
+ *
+ * @param type_mask  int pointer, containing the hooks eurephia will make use of
+ * @param argv       arguments from the openvpn --plugin configuration option.
+ * @param envp       openvpn environmental table
+ *
+ * @return Returns a pointer to the eurephiaCTX.
+ */
 OPENVPN_EXPORT openvpn_plugin_handle_t openvpn_plugin_open_v1(unsigned int *type_mask,
                                                               const char *argv[], const char *envp[])
 {
@@ -122,6 +154,17 @@ OPENVPN_EXPORT openvpn_plugin_handle_t openvpn_plugin_open_v1(unsigned int *type
 }
 
 
+/**
+ * On each hook defined in openvpn_plugin_open_v1(), this function will be called when
+ * openvpn reaches that phase.
+ *
+ * @param handle Contains a pointer to the eurephiaCTX
+ * @param type   What kind of event is openvpn processing now
+ * @param argv   openvpn arguments for the current event
+ * @param envp   openvpn environmental table
+ *
+ * @return Returns OPENVPN_PLUGIN_FUNC_SUCCESS on success, otherwise OPENVPN_PLUGIN_FUNC_ERROR
+ */
 OPENVPN_EXPORT int openvpn_plugin_func_v1(openvpn_plugin_handle_t handle,
                                           const int type,
                                           const char *argv[], const char *envp[])
@@ -144,27 +187,27 @@ OPENVPN_EXPORT int openvpn_plugin_func_v1(openvpn_plugin_handle_t handle,
 #endif
 
         switch( type ) {
-        case OPENVPN_PLUGIN_TLS_VERIFY:
+        case OPENVPN_PLUGIN_TLS_VERIFY:  // Validate certificates
                 result = eurephia_tlsverify(ctx, envp, argv[1]);
                 break;
 
-        case OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY:
+        case OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY: // Validate user name and password
                 result = eurephia_userauth(ctx, envp);
                 break;
 
-        case OPENVPN_PLUGIN_CLIENT_CONNECT:
+        case OPENVPN_PLUGIN_CLIENT_CONNECT:  // Register login
                 result = eurephia_connect(ctx, envp);
                 break;
 
-        case OPENVPN_PLUGIN_CLIENT_DISCONNECT:
+        case OPENVPN_PLUGIN_CLIENT_DISCONNECT: // Register logout
                 result = eurephia_disconnect(ctx, envp);
                 break;
 
-        case OPENVPN_PLUGIN_LEARN_ADDRESS:
+        case OPENVPN_PLUGIN_LEARN_ADDRESS:  // Log IP address, MAC address and update firewall
                 result = eurephia_learn_address(ctx, argv[1], argv[2], envp);
                 break;
 
-        default:
+        default: // This should normally not be reached at all
                 eurephia_log(ctx, LOG_FATAL, 0, "Unknown OPENVPN_PLUGIN type: %i", type);
                 break;
         }
@@ -172,6 +215,12 @@ OPENVPN_EXPORT int openvpn_plugin_func_v1(openvpn_plugin_handle_t handle,
 }
 
 
+/**
+ * Called when openvpn is shutting down.  This makes sure that eurephia disconnects, 
+ * unloads drivers and frees the memory it has been using.
+ *
+ * @param handle  Contains a pointer to the eurephiaCTX
+ */
 OPENVPN_EXPORT void openvpn_plugin_close_v1(openvpn_plugin_handle_t handle)
 {
         eurephiaCTX *ctx = (eurephiaCTX *) handle;
diff --git a/plugin/eurephia.c b/plugin/eurephia.c
index c22471c..2669734 100644
--- a/plugin/eurephia.c
+++ b/plugin/eurephia.c
@@ -19,6 +19,16 @@
  *
  */
 
+/**
+ * @file   eurephia.c
+ * @author David Sommerseth <dazo@users.sourceforge.net>
+ * @date   2008-08-06
+ *
+ * @brief  The core eurephia functions which is called from OpenVPN.
+ *
+ */
+
+
 #include <stdio.h>
 #include <stdlib.h>
 #include <stdarg.h>
@@ -42,7 +52,16 @@
 #define MAX_ARGUMENTS 64
 
 
-// Get value of a environment variable
+/**
+ * get_env() retrieve values from the openvpn environment table
+ *
+ * @param ctx        eurephiaCTX context
+ * @param logmasking If 1, the value will be masked in the log files (eg. to hide password)
+ * @param envp       the environment table
+ * @param fmt        The key to look for (stdarg)
+ *
+ * @return Returns a const char * with the value, or NULL if not found
+ */
 const char *get_env(eurephiaCTX *ctx, int logmasking, const char *envp[], const char *fmt, ... )
 {
         if (envp) {
@@ -87,8 +106,15 @@ const char *get_env(eurephiaCTX *ctx, int logmasking, const char *envp[], const
 }
 
 
-// arguments: logfile loglevel eDB_driver [eurephiaDB arguments]
-//            1       2        3          4.....
+/**
+ * Initialises the eurephia OpenVPN plug-in and prepares a eurephiaCTX (context)
+ *
+ * @param argv  Arguments from the openvpn configuration file.  The format is:
+ *              logfile loglevel eDB_driver [eurephiaDB arguments]
+ *                 1       2        3          4.....
+ *
+ * @return returns a pointer to a eurephiaCTX context.  On failure NULL is returned.
+ */
 eurephiaCTX *eurephiaInit(const char **argv)
 {
         static struct option eurephia_opts[] = {
@@ -224,11 +250,19 @@ eurephiaCTX *eurephiaInit(const char **argv)
                 ctx->eurephia_fw_intf = NULL;
         }
 
-        eurephia_log(ctx, LOG_INFO, 1, "eurehia-auth is initialised");
+        eurephia_log(ctx, LOG_INFO, 1, "eurephia-auth is initialised");
         return ctx;
 }
 
 
+/**
+ * Shutdowns the eurephia plug-in properly, disconnecting from database, unloading drivers,
+ * closing log files and cleaning up the memory used.
+ *
+ * @param ctx  The eurephiaCTX used by openvpn.
+ *
+ * @return Returns 1 on success, otherwise 0.
+ */
 int eurephiaShutdown(eurephiaCTX *ctx)
 {
         if( ctx == NULL ) {
@@ -270,6 +304,15 @@ int eurephiaShutdown(eurephiaCTX *ctx)
 }
 
 
+/**
+ * Verifies the certificate digest (SHA1 fingerprint) against the database.
+ *
+ * @param ctx    eurephiaCTX
+ * @param env    openvpn environment table containing all the information we need
+ * @param depth  If depth is 0, it's a client certificate, or else it's a CA certificate
+ *
+ * @return Returns 0 on failure and 1 on success.
+ */
 int eurephia_tlsverify(eurephiaCTX *ctx, const char **env, const char *depth)
 {
         int result = 0;
@@ -325,6 +368,14 @@ int eurephia_tlsverify(eurephiaCTX *ctx, const char **env, const char *depth)
 }
 
 
+/**
+ * Authenticates the given user name, password and client certificate against the database.
+ *
+ * @param ctx  eurephiaCTX
+ * @param env  openvpn environment table
+ *
+ * @return Returns 0 on failure and 1 on success.
+ */
 int eurephia_userauth(eurephiaCTX *ctx, const char **env)
 {
         eurephiaSESSION *authsess = NULL;
@@ -440,6 +491,15 @@ int eurephia_userauth(eurephiaCTX *ctx, const char **env)
 }
 
 
+/**
+ * Called when openvpn has authenticated the user and granted it access.  This function
+ * will log information about the client
+ *
+ * @param ctx eurephiaCTX
+ * @param env  openvpn environment table
+ *
+ * @return Returns 0 on failure and 1 on success.
+ */
 int eurephia_connect(eurephiaCTX *ctx, const char **env) {
         eurephiaSESSION *session = NULL;
         const char *digest, *cname, *uname, *vpnipaddr, *vpnipmask, *remipaddr, *remport, *proto, *tlsid;
@@ -485,7 +545,14 @@ int eurephia_connect(eurephiaCTX *ctx, const char **env) {
         return ret;
 }
 
-
+/**
+ * Called when the client disconnects.  This function logs some statistics about the session
+ *
+ * @param ctx  eurephiaCTX
+ * @param env  openvpn environment table
+ *
+ * @return Returns 0 on failure and 1 on success.
+ */
 int eurephia_disconnect(eurephiaCTX *ctx, const char **env) {
         eurephiaSESSION *session = NULL;
         const char *digest, *cname, *uname, *vpnipaddr, *vpnipmask, *remipaddr, *remport;
@@ -528,7 +595,19 @@ int eurephia_disconnect(eurephiaCTX *ctx, const char **env) {
         return ret;
 }
 
-
+/**
+ * Called whenever openvpn assigns or changes IP addresses of the client.  The function logs
+ * this information to keep track of which user was assigned which IP address and which MAC address
+ * the user had during the connection as well.  If the firewall interface is enabled, it will also
+ * request an update via the firewall driver.
+ *
+ * @param ctx     eurephiaCTX
+ * @param mode    strings which can be "add", "delete".  In some cases also "update".
+ * @param macaddr string containing the MAC address of the client, if received from openvpn
+ * @param env     openvpn environment table
+ *
+ * @return Returns 0 on failure and 1 on success.
+ */
 int eurephia_learn_address(eurephiaCTX *ctx, const char *mode, const char *macaddr, const char **env) {
         eurephiaSESSION *session = NULL;
         const char *digest, *cname, *uname, *vpnipaddr, *vpnipmask, *remipaddr, *remport;
@@ -567,9 +646,7 @@ int eurephia_learn_address(eurephiaCTX *ctx, const char *mode, const char *macad
                 ret = eDBregister_vpnmacaddr(ctx, session, macaddr);
 
                 if( (fw_enabled) && (fwdest != NULL) ) {
-                        // 1.  Lookup firewall profile for user: eDBget_firewall_profile(ctx, session)
                         fwprofile = eDBget_firewall_profile(ctx, session);
-                        // 2.  Update firewall with eurephia_firewall(ctx, FWRULE_ADD, profileid)
                         if( fwprofile != NULL ) {
                                 eFW_UpdateFirewall(ctx, FWRULE_ADD, macaddr, fwdest, fwprofile);
                                 free_nullsafe(fwprofile);
@@ -592,7 +669,6 @@ int eurephia_learn_address(eurephiaCTX *ctx, const char *mode, const char *macad
                 if( (fw_enabled) && (fwdest != NULL) ) {
                         fwprofile = eDBget_firewall_profile(ctx, session);
                         if( fwprofile != NULL ) {
-                                // 1.  Update firewall with eurephia_firewall(ctx, FWRULE_DELETE, macaddr)
                                 eFW_UpdateFirewall(ctx, FWRULE_DELETE, macaddr, fwdest, fwprofile);
                                 free_nullsafe(fwprofile);
                         }
@@ -607,4 +683,3 @@ int eurephia_learn_address(eurephiaCTX *ctx, const char *mode, const char *macad
 
         return ret;
 }
-
diff --git a/plugin/eurephiadb_session.c b/plugin/eurephiadb_session.c
index f6744e0..d6cd2b2 100644
--- a/plugin/eurephiadb_session.c
+++ b/plugin/eurephiadb_session.c
@@ -19,6 +19,16 @@
  *
  */
 
+/**
+ * @file   eurephiadb_session.c
+ * @author David Sommerseth <dazo@users.sourceforge.net>
+ * @date   2008-08-06
+ *
+ * @brief  Handles creating user sessions, which is unique per openvpn connection.
+ *
+ */
+
+
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
@@ -45,8 +55,21 @@ extern int (*eDBregister_sessionkey) (eurephiaCTX *ctx, const char *seed, const
 
 extern eurephiaVALUES *(*eDBload_sessiondata) (eurephiaCTX *ctx, const char *sesskey);
 
-// Generates a new session structure.  Session key will be created if session seed (input params) are not known.
-// If session seed is known, the already generated session key will be used.
+/**
+ * Generates a new eurephia session.  Session key will be created if session seed (input params) 
+ * are not known.  If session seed is known, the already generated session key will be used.
+ *
+ * @param ctx       eurephiaCTX
+ * @param digest    Contains the clients SHA1 fingerprint / digest
+ * @param cname     Contains the clients X.509 Common Name field
+ * @param username  The user name of the client
+ * @param vpnipaddr The IP address of the VPN connection of the client
+ * @param vpnipmask The IP address' network mask
+ * @param remipaddr The public IP address the client is connecting from
+ * @param remport   The remote port of the client connection
+ *
+ * @return returns a eurephiaSESSION pointer on success, otherwise NULL.
+ */
 eurephiaSESSION *eDBopen_session_seed(eurephiaCTX *ctx, const char *digest,
                                       const char *cname, const char *username,
                                       const char *vpnipaddr, const char *vpnipmask,
@@ -228,7 +251,18 @@ eurephiaSESSION *eDBopen_session_seed(eurephiaCTX *ctx, const char *digest,
         return new_session;
 }
 
-// Open an existing session based on a MAC address
+
+/**
+ * Open an existing eurephia session based on a MAC address.  This function is only used
+ * when there is not enough information to generate a session seed and when the MAC address
+ * is available.  Usually this only happens when the client has disconnected and the session
+ * is about to be marked as closed.
+ *
+ * @param ctx     eurephiaCTX
+ * @param macaddr MAC address of the client
+ *
+ * @return returns a eurephiaSESSION pointer on success, otherwise NULL.
+ */
 eurephiaSESSION *eDBopen_session_macaddr(eurephiaCTX *ctx, const char *macaddr) {
         eurephiaSESSION *new_session = NULL;
 
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;