Added doxygen comments

1 files changed, 60 insertions, 11 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;