Fixed a bug in plugin.c that caused openvpn_plugin_client_destructor_v1

to not be called for the top-level "generic" client template.

Added additional documentation to openvpn-plugin.h that more clearly
illustrates the full sequence and ordering of plugin callbacks
(plugin/defer/simple.c was extended to provide the raw data for this
documentation).


git-svn-id: http://svn.openvpn.net/projects/openvpn/branches/BETA21/openvpn@2973 e7ae566f-a301-0410-adde-c780ea21d3b5

6 files changed, 136 insertions, 13 deletions

diff --git a/memdbg.h b/memdbg.h
index 1aa54b3..65f2e2f 100644
--- a/memdbg.h
+++ b/memdbg.h
@@ -47,6 +47,8 @@
 
 #include "valgrind/memcheck.h"
 
+#define VALGRIND_MAKE_READABLE(addr, len)
+
 #else
 
 #define VALGRIND_MAKE_READABLE(addr, len)
diff --git a/openvpn-plugin.h b/openvpn-plugin.h
index cbcefa0..ceca186 100644
--- a/openvpn-plugin.h
+++ b/openvpn-plugin.h
@@ -27,6 +27,61 @@
 /*
  * Plug-in types.  These types correspond to the set of script callbacks
  * supported by OpenVPN.
+ *
+ * This is the general call sequence to expect when running in server mode:
+ *
+ * Initial Server Startup:
+ *
+ * FUNC: openvpn_plugin_open_v1
+ * FUNC: openvpn_plugin_client_constructor_v1 (this is the top-level "generic"
+ *                                             client template)
+ * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_UP
+ * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_ROUTE_UP
+ *
+ * New Client Connection:
+ *
+ * FUNC: openvpn_plugin_client_constructor_v1
+ * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_VERIFY (called once for every cert
+ *                                                     in the server chain)
+ * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_AUTH_USER_PASS_TLS_VERIFY
+ * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_TLS_FINAL
+ * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_IPCHANGE
+ *
+ * [If OPENVPN_PLUGIN_AUTH_USER_PASS_TLS_VERIFY returned OPENVPN_PLUGIN_FUNC_DEFERRED,
+ * we don't proceed until authentication is verified via auth_control_file]
+ *
+ * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_CLIENT_CONNECT_V2
+ * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_LEARN_ADDRESS
+ * 
+ * [Client session ensues]
+ *
+ * For each "TLS soft reset", according to reneg-sec option (or similar):
+ *
+ * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_VERIFY (called once for every cert
+ *                                                     in the server chain)
+ * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_AUTH_USER_PASS_TLS_VERIFY
+ * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_TLS_FINAL
+ * 
+ * [If OPENVPN_PLUGIN_AUTH_USER_PASS_TLS_VERIFY returned OPENVPN_PLUGIN_FUNC_DEFERRED,
+ * we expect that authentication is verified via auth_control_file within
+ * the number of seconds defined by the "hand-window" option.  Data channel traffic
+ * will continue to flow uninterrupted during this period.]
+ *
+ * [Client session continues]
+ *
+ * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_CLIENT_DISCONNECT
+ * FUNC: openvpn_plugin_client_constructor_v1
+ *
+ * [ some time may pass ]
+ *
+ * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_LEARN_ADDRESS (this coincides with a
+ *                                                            lazy free of initial
+ *                                                            learned addr object)
+ * Server Shutdown:
+ *
+ * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_DOWN
+ * FUNC: openvpn_plugin_client_destructor_v1 (top-level "generic" client)
+ * FUNC: openvpn_plugin_close_v1
  */
 #define OPENVPN_PLUGIN_UP                    0
 #define OPENVPN_PLUGIN_DOWN                  1
diff --git a/plugin.c b/plugin.c
index bff9d49..1c1b545 100644
--- a/plugin.c
+++ b/plugin.c
@@ -401,7 +401,6 @@ plugin_per_client_init (const struct plugin_common *pc,
   const int n = pc->n;
   int i;
 
-  CLEAR (*cli);
   for (i = 0; i < n; ++i)
     {
       const struct plugin *p = &pc->plugins[i];
diff --git a/plugin/defer/build b/plugin/defer/build
index 8b628a2..5907afa 100755
--- a/plugin/defer/build
+++ b/plugin/defer/build
@@ -8,7 +8,7 @@
 # This directory is where we will look for openvpn-plugin.h
 INCLUDE="-I../.."
 
-CC_FLAGS="-O2 -Wall"
+CC_FLAGS="-O2 -Wall -g"
 
 gcc $CC_FLAGS -fPIC -c $INCLUDE $1.c && \
-gcc -fPIC -shared -Wl,-soname,$1.so -o $1.so $1.o -lc
+gcc $CC_FLAGS -fPIC -shared -Wl,-soname,$1.so -o $1.so $1.o -lc
diff --git a/plugin/defer/simple.c b/plugin/defer/simple.c
index 7311a3f..2dcf9f2 100644
--- a/plugin/defer/simple.c
+++ b/plugin/defer/simple.c
@@ -82,25 +82,37 @@ openvpn_plugin_open_v1 (unsigned int *type_mask, const char *argv[], const char
 {
   struct plugin_context *context;
 
+  printf ("FUNC: openvpn_plugin_open_v1\n");
+
   /*
    * Allocate our context
    */
   context = (struct plugin_context *) calloc (1, sizeof (struct plugin_context));
 
   /*
-   * We are only interested in intercepting the
-   * --auth-user-pass-verify callback.
+   * Which callbacks to intercept.  We are only interested in
+   * OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY, but we intercept all
+   * the callbacks for illustration purposes, so we can show
+   * the calling sequence via debug output.
    */
-  *type_mask = OPENVPN_PLUGIN_MASK (OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY);
+  *type_mask =
+    OPENVPN_PLUGIN_MASK (OPENVPN_PLUGIN_UP) |
+    OPENVPN_PLUGIN_MASK (OPENVPN_PLUGIN_DOWN) |
+    OPENVPN_PLUGIN_MASK (OPENVPN_PLUGIN_ROUTE_UP) |
+    OPENVPN_PLUGIN_MASK (OPENVPN_PLUGIN_IPCHANGE) |
+    OPENVPN_PLUGIN_MASK (OPENVPN_PLUGIN_TLS_VERIFY) |
+    OPENVPN_PLUGIN_MASK (OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY) |
+    OPENVPN_PLUGIN_MASK (OPENVPN_PLUGIN_CLIENT_CONNECT_V2) |
+    OPENVPN_PLUGIN_MASK (OPENVPN_PLUGIN_CLIENT_DISCONNECT) |
+    OPENVPN_PLUGIN_MASK (OPENVPN_PLUGIN_LEARN_ADDRESS) |
+    OPENVPN_PLUGIN_MASK (OPENVPN_PLUGIN_TLS_FINAL);
 
   return (openvpn_plugin_handle_t) context;
 }
 
-OPENVPN_EXPORT int
-openvpn_plugin_func_v1 (openvpn_plugin_handle_t handle, const int type, const char *argv[], const char *envp[])
+static int
+auth_user_pass_verify (struct plugin_context *context, const char *argv[], const char *envp[])
 {
-  /* struct plugin_context *context = (struct plugin_context *) handle; */
-
   /* get username/password from envp string array */
   const char *username = get_env ("username", envp);
   const char *password = get_env ("password", envp);
@@ -125,14 +137,69 @@ openvpn_plugin_func_v1 (openvpn_plugin_handle_t handle, const int type, const ch
       return OPENVPN_PLUGIN_FUNC_DEFERRED;
     }
   else
+    return 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[])
+{
+  struct plugin_context *context = (struct plugin_context *) handle;
+  switch (type)
     {
-     return OPENVPN_PLUGIN_FUNC_ERROR;
+    case OPENVPN_PLUGIN_UP:
+      printf ("OPENVPN_PLUGIN_UP\n");
+      return OPENVPN_PLUGIN_FUNC_SUCCESS;
+    case OPENVPN_PLUGIN_DOWN:
+      printf ("OPENVPN_PLUGIN_DOWN\n");
+      return OPENVPN_PLUGIN_FUNC_SUCCESS;
+    case OPENVPN_PLUGIN_ROUTE_UP:
+      printf ("OPENVPN_PLUGIN_ROUTE_UP\n");
+      return OPENVPN_PLUGIN_FUNC_SUCCESS;
+    case OPENVPN_PLUGIN_IPCHANGE:
+      printf ("OPENVPN_PLUGIN_IPCHANGE\n");
+      return OPENVPN_PLUGIN_FUNC_SUCCESS;
+    case OPENVPN_PLUGIN_TLS_VERIFY:
+      printf ("OPENVPN_PLUGIN_TLS_VERIFY\n");
+      return OPENVPN_PLUGIN_FUNC_SUCCESS;
+    case OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY:
+      printf ("OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY\n");
+      return auth_user_pass_verify (context, argv, envp);
+    case OPENVPN_PLUGIN_CLIENT_CONNECT_V2:
+      printf ("OPENVPN_PLUGIN_CLIENT_CONNECT_V2\n");
+      return OPENVPN_PLUGIN_FUNC_SUCCESS;
+    case OPENVPN_PLUGIN_CLIENT_DISCONNECT:
+      printf ("OPENVPN_PLUGIN_CLIENT_DISCONNECT\n");
+      return OPENVPN_PLUGIN_FUNC_SUCCESS;
+    case OPENVPN_PLUGIN_LEARN_ADDRESS:
+      printf ("OPENVPN_PLUGIN_LEARN_ADDRESS\n");
+      return OPENVPN_PLUGIN_FUNC_SUCCESS;
+    case OPENVPN_PLUGIN_TLS_FINAL:
+      printf ("OPENVPN_PLUGIN_TLS_FINAL\n");
+      return OPENVPN_PLUGIN_FUNC_SUCCESS;
+    default:
+      printf ("OPENVPN_PLUGIN_?\n");
+      return OPENVPN_PLUGIN_FUNC_ERROR;
     }
 }
 
+OPENVPN_EXPORT void *
+openvpn_plugin_client_constructor_v1 (openvpn_plugin_handle_t handle)
+{
+  printf ("FUNC: openvpn_plugin_client_constructor_v1\n");
+  return malloc(1);
+}
+
+OPENVPN_EXPORT void
+openvpn_plugin_client_destructor_v1 (openvpn_plugin_handle_t handle, void *per_client_context)
+{
+  printf ("FUNC: openvpn_plugin_client_destructor_v1\n");
+  free (per_client_context);
+}
+
 OPENVPN_EXPORT void
 openvpn_plugin_close_v1 (openvpn_plugin_handle_t handle)
 {
   struct plugin_context *context = (struct plugin_context *) handle;
+  printf ("FUNC: openvpn_plugin_close_v1\n");
   free (context);
 }
diff --git a/plugin/examples/build b/plugin/examples/build
index 8b628a2..5907afa 100755
--- a/plugin/examples/build
+++ b/plugin/examples/build
@@ -8,7 +8,7 @@
 # This directory is where we will look for openvpn-plugin.h
 INCLUDE="-I../.."
 
-CC_FLAGS="-O2 -Wall"
+CC_FLAGS="-O2 -Wall -g"
 
 gcc $CC_FLAGS -fPIC -c $INCLUDE $1.c && \
-gcc -fPIC -shared -Wl,-soname,$1.so -o $1.so $1.o -lc
+gcc $CC_FLAGS -fPIC -shared -Wl,-soname,$1.so -o $1.so $1.o -lc