Added doxygen comments

1 files changed, 85 insertions, 10 deletions

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;
 }
-