diff options
Diffstat (limited to 'database')
| -rw-r--r-- | database/eurephiadb.c | 37 | ||||
| -rw-r--r-- | database/eurephiadb.h | 9 | ||||
| -rw-r--r-- | database/eurephiadb_driver.h | 490 |
3 files changed, 514 insertions, 22 deletions
diff --git a/database/eurephiadb.c b/database/eurephiadb.c index 88e3ac1..235716c 100644 --- a/database/eurephiadb.c +++ b/database/eurephiadb.c @@ -19,6 +19,15 @@ * */ +/** + * @file eurephiadb.c + * @author David Sommerseth <dazo@users.sourceforge.net> + * @date 2008-08-06 + * + * @brief Handles loading and initialising of the database drivers + * + */ + #include <stdio.h> #include <dlfcn.h> @@ -28,6 +37,13 @@ #include "eurephia_getsym.h" +/** + * Unloads the database driver + * + * @param ctx eurephiaCTX + * + * @return Returns always 1. + */ int eDBlink_close(eurephiaCTX *ctx) { if( ctx == NULL ) { @@ -43,18 +59,27 @@ int eDBlink_close(eurephiaCTX *ctx) } -int eDBlink_init(eurephiaCTX *ctx, const char *dbl, const int minver) +/** + * Loads and initialises the database driver. + * + * @param ctx eurephiaCTX to which the database driver will be associated with + * @param dbdriver Full path to the driver file (.so) + * @param minver The required minimum API level of the driver + * + * @return Returns 1 on success, otherwise 0. + */ +int eDBlink_init(eurephiaCTX *ctx, const char *dbdriver, const int minver) { - if( dbl == NULL ) { + if( dbdriver == NULL ) { eurephia_log(ctx, LOG_FATAL, 0, "No eurephia eDBlink driver given. " "eurephia authentication will not be available"); return 0; } - eurephia_log(ctx, LOG_INFO, 2, "Loading eurephiaDB driver: %s", dbl); + eurephia_log(ctx, LOG_INFO, 2, "Loading eurephiaDB driver: %s", dbdriver); - ctx->eurephia_driver = dlopen(dbl, RTLD_NOW); + ctx->eurephia_driver = dlopen(dbdriver, RTLD_NOW); if( ctx->eurephia_driver == NULL ) { - eurephia_log(ctx, LOG_FATAL, 0, "Could not open the eurephia eDBlink driver (%s)", dbl); + eurephia_log(ctx, LOG_FATAL, 0, "Could not open the eurephia eDBlink driver (%s)", dbdriver); eurephia_log(ctx, LOG_FATAL, 1, "dlopen error: %s", dlerror()); return 0; } @@ -80,7 +105,7 @@ int eDBlink_init(eurephiaCTX *ctx, const char *dbl, const int minver) default: eurephia_log(ctx, LOG_WARNING, 0, "eurephiaDB driver API is newer than the running eurephia version. Consider " - "to upgrade eurphia to take advantage of newer features in the eurephiaDB driver."); + "to upgrade eurephia to take advantage of newer features in the eurephiaDB driver."); case 2: #ifdef ENABLE_EUREPHIADM eDBadminAuth = eGetSym(ctx, ctx->eurephia_driver, "eDBadminAuth"); diff --git a/database/eurephiadb.h b/database/eurephiadb.h index 256783c..4dcfd49 100644 --- a/database/eurephiadb.h +++ b/database/eurephiadb.h @@ -19,6 +19,15 @@ * */ +/** + * @file eurephiadb.h + * @author David Sommerseth <dazo@users.sourceforge.net> + * @date 2008-08-06 + * + * @brief Handles loading and initialising of the database drivers + * + */ + #include <eurephia_context.h> #include <eurephiadb_driver.h> #include <eurephia_log.h> diff --git a/database/eurephiadb_driver.h b/database/eurephiadb_driver.h index ab65a91..88522be 100644 --- a/database/eurephiadb_driver.h +++ b/database/eurephiadb_driver.h @@ -18,6 +18,16 @@ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. */ +/** + * @file eurephiadb_driver.h + * @author David Sommerseth <dazo@users.sourceforge.net> + * @date 2008-08-06 + * + * @brief eurephia database driver API. Functions and constants + * provided by and used by the database drivers. + * + */ + #include <eurephia_context.h> #include <eurephiadb_session_struct.h> #include <eurephia_values_struct.h> @@ -29,92 +39,540 @@ #ifndef EUREPHIADB_DRIVER_H_ #define EUREPHIADB_DRIVER_H_ -#define attempt_IPADDR 1 -#define attempt_CERTIFICATE 2 -#define attempt_USERNAME 3 +#define attempt_IPADDR 1 /**< type code for registering attempts on IP address */ +#define attempt_CERTIFICATE 2 /**< type code for registering attempts on certificate */ +#define attempt_USERNAME 3 /**< type code for registering attempts on username */ -#define ATTEMPT_RESET 0x0A -#define ATTEMPT_REGISTER 0x0B +#define ATTEMPT_RESET 0x0A /**< mode code for resetting attempts count */ +#define ATTEMPT_REGISTER 0x0B /**< mode code for registering a new attempt */ -#define USERINFO_user 0x01 -#define USERINFO_certs 0x02 -#define USERINFO_lastlog 0x04 -#define USERINFO_attempts 0x08 -#define USERINFO_blacklist 0x10 +#define USERINFO_user 0x01 /**< flag for extracting user account information */ +#define USERINFO_certs 0x02 /**< flag for extracting certificate information */ +#define USERINFO_lastlog 0x04 /**< flag for extracting lastlog information */ +#define USERINFO_attempts 0x08 /**< flag for extracting information from attempts log */ +#define USERINFO_blacklist 0x10 /**< flag for extracting information from blacklist log */ #ifndef DRIVER_MODE -/* Functions needed by all drivers */ +/** + * Mandatory function. Retrieves driver version information + * + * @return Returns string (const char *) containing driver version information. + */ const char *(*eDB_DriverVersion) (void); -int (*eDB_DriverAPIVersion) (void); +/** + * Mandatory function. Retrieves driver API level + * + * @return Returns integer value with API level supported by driver. + */ +int (*eDB_DriverAPIVersion) (void); + /* - * functions which needs to exists in the eurephiaDB (eDB) module - API Version 1 + * functions which needs to exists in the API level 1 + */ + +/** + * Connect to a database + * + * @version API version level 1 + * @param ctx eurephiaCTX - context to which the database connection will be established against. + * @param argc number of arguments sent in the argument vector + * @param argv char** argument vector with driver specific argument for + * establishing a database connection + * + * @return Returns 1 on success, otherwise 0. */ int (*eDBconnect) (eurephiaCTX *ctx, const int argc, const char **argv); +/** + * Disconnects from a database + * + * @version API version level 1 + * @param ctx eurephiaCTX - context with the database connection to disconnect from. + * + */ void (*eDBdisconnect) (eurephiaCTX *ctx); +/** + * Authenticates a certificate against the database. + * + * @version API version level 1 + * @param ctx eurephiaCTX + * @param org X.509 organisation field (O) + * @param cname X.509 common name field (CN) + * @param email X.509 email field (emailAddress) + * @param digest Certificate SHA1 fingerprint (digest) + * @param depth Certificate depth. 0 is for user certificates. 1 and higher is for CA certificates, + * according to the certificates position in the certificate chain. + * + * @return Returns certid (certificate ID) on success. 0 is returned if certificate is not found, + * or -1 if the certificate is blacklisted. + */ int (*eDBauth_TLS) (eurephiaCTX *ctx, const char *org, const char *cname, const char *email, const char *digest, const char *depth); +/** + * Authenticates a client against the database, with users certificate ID, username and password. + * + * @version API version level 1 + * @param ctx eurephiaCTX + * @param certid certificate ID to the user being authenticated + * @param username username to be authenticated + * @param passwd password provided by the user + * + * @return Returns uicid (user-certs ID) to the user on success. 0 if user account is not + * found and -1 on authentication failure. + */ int (*eDBauth_user) (eurephiaCTX *ctx, const int certid, const char *username, const char *passwd); + +/** + * Retrieve the user ID (uid) for a given user and certificate. + * + * @version API version level 1 + * @param ctx eurephiaCTX + * @param certid Certificate ID of the user + * @param username username of the user + * + * @return Returns uid of user on success, 0 if user account is not found, otherwise -1 on errors. + */ int (*eDBget_uid) (eurephiaCTX *ctx, const int certid, const char *username); + +/** + * Checks if a user account (attempt_USERNAME), certificate (attempt_CERTIFICATE) or + * IP address (attempt_IPADDR) is blacklisted. + * + * @version API version level 1 + * @param eurephiaCTX + * @param type Must be one of the constants: attempt_USERNAME, attempt_CERTIFICATE or attempt_IPADDR + * @param val Value to be checked against the blacklist. + * + * @return Returns 1 if a matching record was found in the blacklist table. Otherwise 0 is returned. + * + * @see attempt_IPADDR, attempt_CERTIFICATE, attempt_USERNAME + */ int (*eDBblacklist_check) (eurephiaCTX *ctx, const int type, const char *val); + +/** + * Registers an attempt in the attempts log. If the number of attempts exceeds the + * configured attempts limit, it will also be blacklisted immediately. + * + * @version API version level 1 + * @param ctx eurephiaCTX + * @param type Must be one of the constants: attempt_USERNAME, attempt_CERTIFICATE or attempt_IPADDR + * @param mode Must be one of the constants: ATTEMPT_RESET to reset the attempts count + * or ATTEMPT_REGISTER to register an attempt. + * @param value Value of the what to be registered. + * + * @see ATTEMPT_REGISTER, ATTEMPT_RESET, attempt_IPADDR, attempt_CERTIFICATE, attempt_USERNAME + */ void (*eDBregister_attempt) (eurephiaCTX *ctx, int type, int mode, const char *value); +/** + * Registers a client login. This happens after the client has been authenticated successfully, + * when OpenVPN does the OPENVPN_PLUGIN_CLIENT_CONNECT call to the eurephia-auth plug-in. + * + * @version API version level 1 + * @param ctx eurephiaCTX + * @param skey eurephiaSESSION. A login must be connected to an opened eurephia session. + * @param certid Certificate ID of the clients user certificate + * @param uid User id of the client + * @param proto String containing protocol used for the connection (udp, tcp) + * @param remipaddr Clients remote IP address + * @param remport The port the client is connecting from + * @param vpnipaddr The IP address openvpn assigned to the user + * @param vpnipmask The VPN networks netmask for the VPN connection. + * + * @return Returns 1 on success, otherwise 0. + */ 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); + +/** + * Registers the MAC address of the clients TAP interface. This function is called when + * OpenVPN does the OPENVPN_PLUGIN_LEARN_ADDRESS call to the eurephia-auth plug-in. + * + * @version API version level 1 + * @param ctx eurephiaCTX + * @param skey eurephiaSESSION of the user + * @param macaddr String (char *) containing the MAC address of the clients interface. + * + * @return Returns 1 on success, otherwise 0. + */ int (*eDBregister_vpnmacaddr) (eurephiaCTX *ctx, eurephiaSESSION *skey, const char *macaddr); + +/** + * Registers when a user logged out. It will then add some information about the session to the + * eurephia lastlog. + * + * @version API version level 1 + * @param ctx eurephiaCTX + * @param skey eurephiaSESSOIN of the user + * @param bytes_sent Amount of bytes the OpenVPN server sent to the client + * @param bytes_received Amount of bytes the OpenVPN server received from the client + * @param duration How long the session lasted (in seconds) + * + * @return Returns 1 on success, otherwise 0. + */ int (*eDBregister_logout) (eurephiaCTX *ctx, eurephiaSESSION *skey, const char *bytes_sent, const char *bytes_received, const char *duration); + /* firewall functions */ +/** + * Retrieves the name of the firewall profile the user access (user account + certificate) + * for the user session + * + * @version API version level 1 + * @param ctx eurephiaCTX + * @param session eurephiaSESSION + * + * @return Returns a char pointer to a buffer with the name of the firewall profile. This buffer + * must be freed when no longer needed. + */ char *(*eDBget_firewall_profile) (eurephiaCTX *ctx, eurephiaSESSION *session); + +/** + * Retrieve a list of IP addresses found in the IP address blacklist table. + * + * @version API version level 1 + * @param eurephiaCTX + * + * @return Returns an eurephiaVALUES chain with all blacklisted IP addresses on success, otherwise + * NULL is returned + */ eurephiaVALUES *(*eDBget_blacklisted_ip) (eurephiaCTX *ctx); /* The following functions is also declared in eurephia_session_values.c - for local internal usage. */ +/** + * Retrieve a unique session key based on a session seed. + * + * @version API version level 1 + * @param ctx eurephiaCTX + * @param type Must be either stSESSION for a normal session or stAUTHENTICATION for an + * authentication session (before the user is really logged in) + * @param sessionseed session seed of the current connection + * + * @return Returns the unique session key string (char *) on success, otherwise NULL. The session key + * string must be freed when no longer needed. + */ char *(*eDBget_sessionkey_seed) (eurephiaCTX *ctx, sessionType type, const char *sessionseed); + + +/** + * Retrieve a unique session key based on a connections MAC address. This is called when + * OpenVPN is removing the MAC address of the client as a known connection. + * + * @version API version level 1 + * @param ctx eurephiaCTX + * @param macaddr String (char *) containing the MAC address of the client + * + * @return Returns the unique session key string (char *) on success, otherwise NULL. The session key + * string must be freed when no longer needed. + */ char *(*eDBget_sessionkey_macaddr) (eurephiaCTX *ctx, const char *macaddr); + + +/** + * Check if a session key is unique. In other words, it will check the given session key + * against the database to see if it is found there or not. If not, it is unique. + * + * @version API version level 1 + * @param ctx eurephiaCTX + * @param seskey String containing the session key + * + * @return Returns 1 if the session key is unique and not been used earlier. + */ int (*eDBcheck_sessionkey_uniqueness) (eurephiaCTX *ctx, const char *seskey); + +/** + * Registers a new session key against a short-term session seed. + * + * @version API version level 1 + * @param ctx eurephiaCTX + * @param seed A string (char *) containing the short-term session seed + * @param seskey A string (char *) containing the new unique session key + * + * @return Returns 1 on success, otherwise 0 + */ int (*eDBregister_sessionkey) (eurephiaCTX *ctx, const char *seed, const char *seskey); + +/** + * Loads all session variables for a specified session key. This is key/value pairs + * which are unique for each connection. + * + * @version API version level 1 + * @param ctx eurephiaCTX + * @param sesskey String (char *) containing a session key + * + * @return Returns a pointer to an eurephiaVALUES pointer chain with all the variables available + * for the given session. On errors, it will return an empty eurephiaVALUES chain. + */ eurephiaVALUES *(*eDBload_sessiondata) (eurephiaCTX *ctx, const char *sesskey); + +/** + * Destroys a session. It will remove all stored session variables and mark the session + * as closed in the lastlog. It will also remove the session seed/session key reference. + * + * @version API version level 1 + * @param ctx eurephiaCTX + * @param session eurephiaSESSION pointer to session to be destroyed + * + * @return Returns 1 on success, otherwise 0. + */ int (*eDBdestroy_session) (eurephiaCTX *ctx, eurephiaSESSION *session); + +/** + * Add, update or remove a session variable from the database. This operation is + * only affecting the given session. This function will only update the database itself. + * + * @version API version level 1 + * @param ctx eurephiaCTX + * @param skey eurephiaSESSION to which the variable will be added, modified or deleted + * @param mode Must be one of the constants: SESSVAL_NEW, SESSVAL_UPDATE, SESSVAL_DELETE + * @param key Key name for the value to be stored + * @param val Value to be stored + * + * @return Returns 1 on success, otherwise 0 + * + * @see SESSVAL_NEW, SESSVAL_UPDATE, SESSVAL_DELETE + */ int (*eDBstore_session_value) (eurephiaCTX *ctx, eurephiaSESSION *skey, int mode, const char *key, const char *val); -/* API version 2 functions */ +/* + * functions which needs to exists in the API level 2 + */ +/** + * Authenticate a user for the administration interface. This interface do not + * require any certificate validation and is intended for administration utilities + * for eurephia. The eurephia context type must be either ECTX_ADMIN_CONSOLE or + * ECTX_ADMIN_WEB. + * + * @version API version level 2 + * @param ctx eurephiaCTX - context used for administration task + * @param req_acc String (char *) containing the requested administration access level + * @param uname username of the user being authenticated + * @param pwd password from the user + * + * @return Returns users ID (uid) on success, otherwise 0 + */ int (*eDBadminAuth) (eurephiaCTX *ctx, const char *req_acc, const char *uname, const char *pwd); + + +/** + * Validates a session key, to see if it still is valid (not auto-logged out or invalid session key) + * and to check if they have access to a different access level. The eurephia context type must be + * either ECTX_ADMIN_CONSOLE or ECTX_ADMIN_WEB. + * + * @version API version level 2 + * @param ctx eurephiaCTX + * @param sesskey String (char *) containing the session key to validate + * @param req_acc String (char *) containing the required administration access level + * + * @return Returns 1 if the session is valid and the user have the needed privileges, + * otherwise 0 is returned. + */ int (*eDBadminValidateSession) (eurephiaCTX *ctx, const char *sesskey, const char *req_acc); + + +/** + * Registers the user as logged in after a successful authentication. The user must + * be registered as logged in to have a valid session. + * + * @version API version level 2 + * @param ctx eurephiaCTX + * @param session eurephiaSESSION + * + * @return Returns 1 on success, otherwise 0 + */ int (*eDBadminRegisterLogin) (eurephiaCTX *ctx, eurephiaSESSION *session); + + +/** + * Registers a session as logged out. This will require the user to do a new authentication + * on next access via the administration interface + * + * @version API version level 2 + * @param ctx eurephiaCTX + * @param session String (char *) containing the session key + * + * @return Returns 1 on success, otherwise 0 + */ int (*eDBadminLogout) (eurephiaCTX *ctx, const char *session); + +/** + * Sets a configuration parameter in the database. If the key already exists, it will + * be replaced. This operation will immediately update the in-memory copy of the setting. + * + * @version API version level 2 + * @param ctx eurephiaCTX + * @param key String (char *) containing the key name of the value + * @param val String (char *) with the value to be stored + * + * @return Returns 1 on success, otherwise 0 + */ int (*eDBadminConfigSet) (eurephiaCTX *ctx, const char *key, const char *val); + + +/** + * Deletes a configuration parameter from the database. + * + * @version API version level 2 + * @param ctx eurephiaCTX + * @param key String (char *) containing the key to be deleted. + * + * @return Returns 1 on success, otherwise 0 + */ int (*eDBadminConfigDelete) (eurephiaCTX *ctx, const char *key); + #ifdef HAVE_LIBXML2 +/** + * Retrieve a list over all users in the database. + * + * @version API version level 2 + * @param ctx eurephiaCTX + * @param sortkeys String containing the sort order of the fields + * + * @return Returns an XML document on success with all users, otherwise NULL + */ xmlDoc *(*eDBadminGetUserList) (eurephiaCTX *ctx, const char *sortkeys); + + +/** + * This function will search up a user, based on information given in a fieldMapping structure. + * It will return an XML document containing the user information requested, controlled by the + * getInfo flag. These flags are defined in eurephiadb_driver.h + * + * @version API version level 2 + * @param ctx eurephiaCTX + * @param infoType Flags of what information to extract. Valid flags are: USERINFO_user, + * USERINFO_certs, USERINFO_lastlog, USERINFO_attempts, USERINFO_blacklist. + * These flags can be bit-wise OR'ed together to extract more information + * at once. + * + * @param srch XML document describing the search criteria + * + * Skeleton of an XML search document + * @code + * <eurephia format="1"> + * <fieldMapping table="users"> + * <{search field}>{search value}</{search field}> + * </fieldMapping> + * </eurephia> + * @endcode + * + * @return Returns an XML document containing the requested user information on success, otherwise + * NULL is returned. + * + * @see eurephiaXML_CreateDoc() + * @see USERINFO_user, USERINFO_certs, USERINFO_lastlog, USERINFO_attempts, USERINFO_blacklist + */ xmlDoc *(*eDBadminGetUserInfo) (eurephiaCTX *ctx, int infoType, xmlDoc *srch); + + +/** + * This function will add a user to the openvpn_users table, based on the + * XML document given. + * + * @version API version level 2 + * @param ctx eurephiaCTX + * @param userinfo XML document containing information about the new user + * + * Skeleton of an XML document for adding a new user + * @code + * <eurephia format="1"> + * <add_user> + * <fieldMapping table="users"> + * <username>{user name}</username> + * <password pwhash="{none|sha512}">{password}</password> + * </fieldMapping> + * </add_user> + * </eurephia> + * @endcode + * + * The password tag can use either a clear-text password (by setting pwhash="none") or a pre-hashed + * SHA512 password (by setting pwhash="sha512"). Beware that the SHA512 hash must be hashed with + * the eurephia_pwd_crypt() function. + * + * @return Returns the user ID (uid) of the new user account on success, otherwise -1 is returned. + * + * @see eurephiaXML_CreateDoc(), eurephia_pwd_crypt() + */ int (*eDBadminAddUser) (eurephiaCTX *ctx, xmlDoc *userinfo); + + +/** + * This function will update a user account based on the XML document sent in as a parameter. + * The function will double check that the uid in the argument list and the uid in the XML + * document is coherent. + * + * @version API version level 2 + * @param ctx eurephiaCTX + * @param uid Numeric user ID of the user account being updated + * @param userinfo XML document containing the new information for the user account + * + * Skeleton of an XML document updating a user + * @code + * <eurephia format="1"> + * <update_user uid="{uid}"> + * <fieldMapping table="users"> + * <{field name}>{new value}</{field name}> + * </fieldMapping> + * </update_user> + * </eurephia> + * @endcode + * @remarks Beware that the uid attribute in the update_user tag must be the same user ID given as + * argument to the function. + * + * @return Returns 1 on success, otherwise 0. + * + * @see eurephiaXML_CreateDoc() + */ int (*eDBadminUpdateUser) (eurephiaCTX *ctx, const int uid, xmlDoc *userinfo); + + +/** + * This function will delete a user to the openvpn_users table, based on the + * XML document given. + * + * @version API version level 2 + * @param ctx eurephiaCTX + * @param uid Numeric user ID of the user account being updated + * @param userinfo XML document containing information about the account which is going to be deleted + * + * @code + * <eurephia format="1"> + * <delete_user uid="{uid}"/> + * </eurephia> + * @endcode + * @remarks The uid of the account to be deleted must also be sent + * as a separate parameter, as a security feature + * + * @return Returns 1 on success, otherwise 0. + * + * @see eurephiaXML_CreateDoc() + */ int (*eDBadminDeleteUser) (eurephiaCTX *ctx, const int uid, xmlDoc *userinfo); xmlDoc *(*eDBadminGetCertificateList) (eurephiaCTX *ctx, const char *sortkeys); xmlDoc *(*eDBadminGetCertificateInfo) (eurephiaCTX *ctx, xmlDoc *searchkey, const char *sortkeys); -int (*eDBadminAddCertificate) (eurephiaCTX *ctx, xmlDoc *certinfo); -int (*eDBadminDeleteCertificate) (eurephiaCTX *ctx, xmlDoc *certinfo); +int (*eDBadminAddCertificate) (eurephiaCTX *ctx, xmlDoc *certinfo_xml); +int (*eDBadminDeleteCertificate) (eurephiaCTX *ctx, xmlDoc *certinfo_xml); xmlDoc *(*eDBadminUserCertsLink) (eurephiaCTX *ctx, xmlDoc *usrcrt_xml); |