Completed doxygen comments for edb-sqlite.c

1 files changed, 114 insertions, 37 deletions

diff --git a/database/sqlite/edb-sqlite.c b/database/sqlite/edb-sqlite.c
index d4ef84d..25d5a10 100644
--- a/database/sqlite/edb-sqlite.c
+++ b/database/sqlite/edb-sqlite.c
@@ -20,15 +20,26 @@
  *
  */
 
+/**
+ * @file   edb-sqlite.c
+ * @author David Sommerseth <dazo@users.sourceforge.net>
+ * @date   2008-08-06
+ *
+ * @brief  eurephia database driver for the SQLite3 database.
+ *         This file is the main API for the driver.
+ *
+ */
+
+
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
 #include <unistd.h>
 #include <assert.h>
 
-#define DRIVERVERSION "1.1"
+#define DRIVERVERSION "1.1"     /**< Defines the software version of this driver */
 #ifndef DRIVERAPIVERSION
-# define DRIVERAPIVERSION 2
+# define DRIVERAPIVERSION 2     /**< Sets the API version level of this driver */
 #endif
 
 #include <sqlite3.h>
@@ -44,15 +55,22 @@
 #include "sqlite.h"
 
 
-// Mapping table - mapping attempt types from .... to sqlite table fields
+
+/**
+ * Mapping struct - maps attempt types (attempt_IPADDR, attempt_CERTIFICATE, attempt_USERNAME)
+ * to database field names, configuration options (with default values) and description
+ */
 typedef struct {
-        char *colname;
-        char *allow_cfg;
-        char *descr;
-        char *default_value;
+        char *colname;		/**< Column name when doing look up in blacklist and attempts tables */
+        char *allow_cfg;	/**< Configure parameter for the attempt limits */
+        char *descr;		/**< Description, used to give more readable output for users */
+        char *default_value;	/**< Default value, if config option is not found */
 } eDBattempt_types_t;
                
 
+/**
+ *  Static mapping table with the needed values.  Uses the eDBattempt_types_t struct.
+ */
 static const eDBattempt_types_t eDBattempt_types[] = {
         {NULL, NULL, NULL},
         {"remoteip\0", "allow_ipaddr_attempts\0", "IP Address\0", "10\0"},
@@ -61,15 +79,18 @@ static const eDBattempt_types_t eDBattempt_types[] = {
         {NULL, NULL, NULL}
 };
 
-/*
- *   Driver info
- */
 
-const char *eDB_DriverVersion() {
+/**
+ * @copydoc eDB_DriverVersion()
+ */
+const char *eDB_DriverVersion(void) {
         return "eurephiadb-sqlite (v"DRIVERVERSION")  David Sommerseth 2008 (C) GPLv2";
 }
 
 
+/**
+ * @copydoc eDB_DriverAPIVersion()
+ */
 int eDB_DriverAPIVersion() {
         return DRIVERAPIVERSION;
 }
@@ -80,7 +101,13 @@ int eDB_DriverAPIVersion() {
  */
 
 
-// Function for simplifying update of openvpn_blacklist
+/**
+ * Internal driver function for simplifying update of openvpn_blacklist.  It will simply just
+ * update the 'last_accessed' field in the blacklist table.
+ *
+ * @param ctx  eurephiaCTX
+ * @param blid Blacklist ID, integer value corresponding to the record in the database
+ */
 void update_attempts(eurephiaCTX *ctx, const char *blid) {
         dbresult *res = NULL;
 
@@ -100,7 +127,10 @@ void update_attempts(eurephiaCTX *ctx, const char *blid) {
  *   Public driver functions
  */
 
-// Connect to the database ... connection is stored in the eurephiaCTX context
+/**
+ * @copydoc eDBconnect()
+ * Connect to the database ... connection is stored in the eurephiaCTX context
+ */
 int eDBconnect(eurephiaCTX *ctx, const int argc, const char **argv)
 {
         eDBconn *dbc = NULL;
@@ -153,7 +183,10 @@ int eDBconnect(eurephiaCTX *ctx, const int argc, const char **argv)
         return 1;
 }
 
-// Disconnect from the database
+/**
+ * @copydoc eDBdisconnect()
+ * Disconnect from the database
+ */
 void eDBdisconnect(eurephiaCTX *ctx) 
 {
         eDBconn *dbc = NULL;
@@ -180,8 +213,9 @@ void eDBdisconnect(eurephiaCTX *ctx)
 }
 
 
-// Authenticate certificate ... returns certid (certificate ID) on success, 
-// 0 if not found or -1 if certificate is blacklisted
+/**
+ * @copydoc eDBauth_TLS()
+ */
 int eDBauth_TLS(eurephiaCTX *ctx, const char *org, const char *cname, const char *email, 
                 const char *digest, const char *depth)
 {
@@ -225,8 +259,10 @@ int eDBauth_TLS(eurephiaCTX *ctx, const char *org, const char *cname, const char
         return certid;
 }
 
-// Authenticate user, using username, password and certid as authentication parameters
-// returns -1 if authentication fails.  Returns 0 if user account is not found.
+
+/**
+ * @copydoc eDBauth_user()
+ */
 int eDBauth_user(eurephiaCTX *ctx, const int certid, const char *username, const char *passwd) 
 {
         dbresult *res = NULL;
@@ -329,7 +365,9 @@ int eDBauth_user(eurephiaCTX *ctx, const int certid, const char *username, const
         return uicid;
 }
 
-// Retrieve the user id from openvpn_usercerts, based on certid and username
+/**
+ * @copydoc eDBget_uid()
+ */
 int eDBget_uid(eurephiaCTX *ctx, const int certid, const char *username)  
 {
         dbresult *res = NULL;
@@ -355,7 +393,9 @@ int eDBget_uid(eurephiaCTX *ctx, const int certid, const char *username)
 }
 
 
-// If function returns true(1) this control marks it as blacklisted
+/**
+ * @copydoc eDBblacklist_check()
+ */
 int eDBblacklist_check(eurephiaCTX *ctx, const int type, const char *val)
 {
         dbresult *blr = NULL, *atpr = NULL;
@@ -429,7 +469,9 @@ int eDBblacklist_check(eurephiaCTX *ctx, const int type, const char *val)
         return blacklisted;
 }
 
-// Register a failed attempt of authentication or IP address has been tried to many times
+/**
+ * @copydoc eDBregister_attempt()
+ */
 void eDBregister_attempt(eurephiaCTX *ctx, int type, int mode, const char *value) {
         dbresult *res;
         char *id = NULL, *atmpt_block = NULL, *blid = NULL;
@@ -517,7 +559,9 @@ void eDBregister_attempt(eurephiaCTX *ctx, int type, int mode, const char *value
 }
 
 
-// Register a successful authentication
+/**
+ * @copydoc eDBregister_login()
+ */
 int eDBregister_login(eurephiaCTX *ctx, eurephiaSESSION *skey, const int certid, const int uid, 
                       const char *proto, const char *remipaddr, const char *remport, 
                       const char *vpnipaddr, const char *vpnipmask) 
@@ -548,7 +592,9 @@ int eDBregister_login(eurephiaCTX *ctx, eurephiaSESSION *skey, const int certid,
         return 1;
 }
 
-// Register the MAC address of the VPN adapter of the user.
+/**
+ * @copydoc eDBregister_vpnmacaddr()
+ */
 int eDBregister_vpnmacaddr(eurephiaCTX *ctx, eurephiaSESSION *session, const char *macaddr)
 {
         dbresult *res = NULL;
@@ -591,7 +637,9 @@ int eDBregister_vpnmacaddr(eurephiaCTX *ctx, eurephiaSESSION *session, const cha
 }
 
 
-// Register the user as logged out
+/**
+ * @copydoc eDBregister_logout()
+ */
 int eDBregister_logout(eurephiaCTX *ctx, eurephiaSESSION *skey, 
                        const char *bytes_sent, const char *bytes_received, const char *duration)
 {
@@ -618,13 +666,14 @@ int eDBregister_logout(eurephiaCTX *ctx, eurephiaSESSION *skey,
 }
 
 
-// Retrieve a session key from openvpn_sessionkeys if it is a current session.  Session seed is used
-// as criteria
-char *eDBget_sessionkey_seed(eurephiaCTX *ctx, sessionType sesstype, const char *sessionseed) {
+/**
+ * @copydoc eDBget_sessionkey_seed()
+ */
+char *eDBget_sessionkey_seed(eurephiaCTX *ctx, sessionType type, const char *sessionseed) {
         dbresult *res = NULL;
         char *skey = NULL;
 
-        DEBUG(ctx, 20, "eDBget_sessionkey_seed(ctx, %i, '%s')", sesstype, sessionseed);
+        DEBUG(ctx, 20, "eDBget_sessionkey_seed(ctx, %i, '%s')", type, sessionseed);
 
         if( sessionseed == NULL ) {
                 eurephia_log(ctx, LOG_FATAL, 1,
@@ -632,7 +681,7 @@ char *eDBget_sessionkey_seed(eurephiaCTX *ctx, sessionType sesstype, const char
                 return NULL;
         }
 
-        switch( sesstype ) {
+        switch( type ) {
         case stSESSION:
                 res = sqlite_query(ctx,
                                    "SELECT sessionkey "
@@ -654,7 +703,7 @@ char *eDBget_sessionkey_seed(eurephiaCTX *ctx, sessionType sesstype, const char
                 break;
 
         default:
-                eurephia_log(ctx, LOG_ERROR, 0, "Invalid session type: %i", sesstype);
+                eurephia_log(ctx, LOG_ERROR, 0, "Invalid session type: %i", type);
                 return NULL;
         }
 
@@ -672,6 +721,10 @@ char *eDBget_sessionkey_seed(eurephiaCTX *ctx, sessionType sesstype, const char
         return skey;
 }
 
+
+/**
+ * @copydoc eDBget_sessionkey_macaddr()
+ */
 char *eDBget_sessionkey_macaddr(eurephiaCTX *ctx, const char *macaddr) {
         dbresult *res = NULL;
         char *skey = NULL;
@@ -698,7 +751,9 @@ char *eDBget_sessionkey_macaddr(eurephiaCTX *ctx, const char *macaddr) {
 }
 
 
-// Function returns true(1) if session key is unique
+/**
+ * @copydoc eDBcheck_sessionkey_uniqueness()
+ */
 int eDBcheck_sessionkey_uniqueness(eurephiaCTX *ctx, const char *seskey) {
         dbresult *res;
         int uniq = 0;
@@ -742,7 +797,9 @@ int eDBcheck_sessionkey_uniqueness(eurephiaCTX *ctx, const char *seskey) {
 }
 
 
-// register a link between a short-term session seed and a long-term session key
+/**
+ * @copydoc eDBregister_sessionkey()
+ */
 int eDBregister_sessionkey(eurephiaCTX *ctx, const char *seed, const char *seskey) {
         dbresult *res;
 
@@ -765,7 +822,15 @@ int eDBregister_sessionkey(eurephiaCTX *ctx, const char *seed, const char *seske
         return 1;
 }
 
-// remove a session seed/session key link from openvpn_sessionkeys
+/**
+ * Removes a session key reference to a short time session seed conversion table
+ *
+ * @param ctx     eurephiaCTX
+ * @param seskey  String containing the session key reference to remove
+ *
+ * @return Returns 1 on success, otherwise 0.
+ *
+ */
 int eDBremove_sessionkey(eurephiaCTX *ctx, const char *seskey) {
         dbresult *res;
 
@@ -786,7 +851,9 @@ int eDBremove_sessionkey(eurephiaCTX *ctx, const char *seskey) {
         return 1;
 }
 
-// Load session values stored in the database into a eurephiaVALUES struct (session values)
+/**
+ * @copydoc eDBload_sessiondata()
+ */
 eurephiaVALUES *eDBload_sessiondata(eurephiaCTX *ctx, const char *sesskey) {
         dbresult *res = NULL;
         eurephiaVALUES *sessvals = NULL;
@@ -817,8 +884,9 @@ eurephiaVALUES *eDBload_sessiondata(eurephiaCTX *ctx, const char *sesskey) {
         return sessvals;
 }
 
-
-// Store a new, update or delete a sessionvalue in the database
+/**
+ * @copydoc eDBstore_session_value()
+ */
 int eDBstore_session_value(eurephiaCTX *ctx, eurephiaSESSION *session, int mode, const char *key, const char *val) 
 {
         dbresult *res = NULL;
@@ -878,7 +946,9 @@ int eDBstore_session_value(eurephiaCTX *ctx, eurephiaSESSION *session, int mode,
 }
 
 
-// Delete session information from openvpn_sessions and update openvpn_lastlog with status
+/**
+ * @copydoc eDBdestroy_session()
+ */
 int eDBdestroy_session(eurephiaCTX *ctx, eurephiaSESSION *session) {
         dbresult *res = NULL;
         
@@ -920,6 +990,9 @@ int eDBdestroy_session(eurephiaCTX *ctx, eurephiaSESSION *session) {
 }
 
 
+/**
+ * @copydoc eDBget_firewall_profile()
+ */
 char *eDBget_firewall_profile(eurephiaCTX *ctx, eurephiaSESSION *session) 
 {
         char *ret = NULL;
@@ -944,6 +1017,10 @@ char *eDBget_firewall_profile(eurephiaCTX *ctx, eurephiaSESSION *session)
         return ret;
 }
 
+
+/**
+ * @copydoc eDBget_blacklisted_ip()
+ */
 eurephiaVALUES *eDBget_blacklisted_ip(eurephiaCTX *ctx) {
         eurephiaVALUES *ret = NULL;
         dbresult *res = NULL;