From 201677bb8b384306e09a84c90b7f18fbc879d626 Mon Sep 17 00:00:00 2001 From: David Sommerseth Date: Wed, 2 Sep 2009 18:53:29 +0200 Subject: Added doxygen comments --- plugin/eurephia-auth.c | 71 ++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 60 insertions(+), 11 deletions(-) (limited to 'plugin/eurephia-auth.c') 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 + * @date 2008-08-06 + * + * @brief Implements the API which the OpenVPN plug-in interface requires + * + */ + #include #include @@ -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; -- cgit