Skip to contentSkip to conversation

New OpenVPN plug-in API

PATCH Superseded David Sommerseth 2 participants 5 messages Aug 26, 2010 – Aug 27, 2010

v1 of 2 Superseded Latest is v2 →

lore
Share & tools
lore
#0 lore raw

cover New OpenVPN plug-in API

In the IRC meeting August 26, the current plug-in API was discussed in relation to a Trac ticket [1] which requested access to the complete X509 certificate structures.

Several approaches was discussed, but a consensus was met that the current plug-in API was not flexible enough to tackle this. Instead of creating yet another API which just adds the X509 structures usable by OpenSSL, it was decided to try to design a new API which could be extended more easily in the future, without implementing new functions constantly.

This patch series is a first-stab at such an a design. It is designed to support all the features of the v2 API, but the arguments to openvpn_plugin_open_v3() and openvpn_plugin_func_v3() is different. Most of the input arguments, are now sent as a struct in stead.

The X509 certificate data is not yet provided via the plug-in as the ticket [1] requests, but it prepares the ground to add this information later on when a new plug-in API has been accepted and implemented.

Kind regards,

David Sommerseth

[1] https://community.openvpn.net/openvpn/ticket/44

David Sommerseth (3):
Define the new openvpn_plugin_{open,func}_v3() API Implement the core v3 plug-in function calls. Added a simple plug-in demonstrating the v3 plug-in API.

 openvpn-plugin.h         |  181 ++++++++++++++++++++++++++++++++++++++++++++-
 plugin.c                 |   23 +++++-
 plugin.h                 |    2 +
 plugin/examples/log_v3.c |  188 ++++++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 389 insertions(+), 5 deletions(-)
 create mode 100644 plugin/examples/log_v3.c
Signature · 1 line
1.7.2.2
#1 lore raw

PATCH 1/3 Define the new openvpn_plugin_{open, func}_v3() API

This just implements the basic API changes needed for the newer and more flexible plug-in API.

---
 openvpn-plugin.h |  181 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 plugin.c         |    6 +-
 plugin.h         |    2 +
 3 files changed, 186 insertions(+), 3 deletions(-)
openvpn-plugin.h +180 -1
index ac683f2..2c534b0 100644
@@ -22,7 +22,7 @@
  *  59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  */
 
-#define OPENVPN_PLUGIN_VERSION 2
+#define OPENVPN_PLUGIN_VERSION 3
 
 /*
  * Plug-in types.  These types correspond to the set of script callbacks
@@ -162,6 +162,80 @@ struct openvpn_plugin_string_list
   char *value;
 };
 
+
+/* openvpn_plugin_{open,func}_v3() related structs */
+
+#define OPENVPN_PLUGIN_ARGS_APIVER 1  /** Defines the defined struct API version*/
+
+/**
+ * Aruguments used to transport variables to and from the
+ * plug-in.  The struct openvpn_plugin_args_open is only used
+ * by the openvpn_plugin_open_v3() function.
+ *
+ * STRUCT MEMBERS
+ *
+ * *type_mask : Set by OpenVPN to the logical OR of all script
+ *              types which this version of OpenVPN supports.  The plug-in
+ *              should set this value to the logical OR of all script types
+ *              which the plug-in wants to intercept.  For example, if the
+ *              script wants to intercept the client-connect and
+ *              client-disconnect script types:
+ *
+ *              *type_mask = OPENVPN_PLUGIN_MASK(OPENVPN_PLUGIN_CLIENT_CONNECT)
+ *                         | OPENVPN_PLUGIN_MASK(OPENVPN_PLUGIN_CLIENT_DISCONNECT)
+ *
+ * argv : a NULL-terminated array of options provided to the OpenVPN
+ *        "plug-in" directive.  argv[0] is the dynamic library pathname.
+ *
+ * envp : a NULL-terminated array of OpenVPN-set environmental
+ *        variables in "name=value" format.  Note that for security reasons,
+ *        these variables are not actually written to the "official"
+ *        environmental variable store of the process.
+ */
+struct openvpn_plugin_args_open
+{
+  const int version;
+  int  *type_mask;
+  const char const **argv;
+  const char const **envp;
+};
+
+
+/**
+ * Aruguments used to transport variables to and from the
+ * plug-in.  The struct openvpn_plugin_args_func is only used
+ * by the openvpn_plugin_func_v3() function.
+ *
+ * STRUCT MEMBERS:
+ *
+ * version : fixed value, defines the API version of the struct.  This is defined
+ *        by OPENVPN_PLUGIN_ARGS_APIVER.  Your plug-in should check that this value is
+ *        not lower than the OPENVPN_PLUGIN_ARGS_APIVER version you have implemented.
+ *
+ * type : one of the PLUGIN_x types.
+ *
+ * argv : a NULL-terminated array of "command line" options which
+ *        would normally be passed to the script.  argv[0] is the dynamic
+ *        library pathname.
+ *
+ * envp : a NULL-terminated array of OpenVPN-set environmental
+ *        variables in "name=value" format.  Note that for security reasons,
+ *        these variables are not actually written to the "official"
+ *        environmental variable store of the process.
+ *
+ * per_client_context : the per-client context pointer which was returned by
+ *        openvpn_plugin_client_constructor_v1, if defined.
+
+ */
+struct openvpn_plugin_args_func
+{
+  const int version;
+  const int type;
+  const char const **argv;
+  const char const **envp;
+  void *per_client_context;
+};
+
 /*
  * Multiple plugin modules can be cascaded, and modules can be
  * used in tandem with scripts.  The order of operation is that
@@ -328,6 +402,111 @@ OPENVPN_PLUGIN_DEF int OPENVPN_PLUGIN_FUNC(openvpn_plugin_func_v2)
       void *per_client_context,
       struct openvpn_plugin_string_list **return_list);
 
+
+/*
+ * FUNCTION: openvpn_plugin_open_v3
+ *
+ * REQUIRED: YES
+ *
+ * Called on initial plug-in load.  OpenVPN will preserve plug-in state
+ * across SIGUSR1 restarts but not across SIGHUP restarts.  A SIGHUP reset
+ * will cause the plugin to be closed and reopened.
+ *
+ * ARGUMENTS
+ *
+ * arguments : Structure with all arguments available to the plug-in.
+ *
+ * return_list : used to return data back to OpenVPN.
+ *
+ * RETURN VALUE
+ *
+ * An openvpn_plugin_handle_t value on success, NULL on failure
+ */
+OPENVPN_PLUGIN_DEF openvpn_plugin_handle_t OPENVPN_PLUGIN_FUNC(openvpn_plugin_open_v3)
+      (struct openvpn_plugin_args_open const *arguments,
+       struct openvpn_plugin_string_list **return_list);
+
+/*
+ * FUNCTION: openvpn_plugin_func_v3
+ *
+ * Called to perform the work of a given script type.
+ *
+ * REQUIRED: YES
+ *
+ * ARGUMENTS
+ *
+ * handle : the openvpn_plugin_handle_t value which was returned by
+ *          openvpn_plugin_open.
+ *
+ * return_list : used to return data back to OpenVPN.
+ *
+ * RETURN VALUE
+ *
+ * OPENVPN_PLUGIN_FUNC_SUCCESS on success, OPENVPN_PLUGIN_FUNC_ERROR on failure
+ *
+ * In addition, OPENVPN_PLUGIN_FUNC_DEFERRED may be returned by
+ * OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY.  This enables asynchronous
+ * authentication where the plugin (or one of its agents) may indicate
+ * authentication success/failure some number of seconds after the return
+ * of the OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY handler by writing a single
+ * char to the file named by auth_control_file in the environmental variable
+ * list (envp).
+ *
+ * first char of auth_control_file:
+ * '0' -- indicates auth failure
+ * '1' -- indicates auth success
+ *
+ * OpenVPN will delete the auth_control_file after it goes out of scope.
+ *
+ * If an OPENVPN_PLUGIN_ENABLE_PF handler is defined and returns success
+ * for a particular client instance, packet filtering will be enabled for that
+ * instance.  OpenVPN will then attempt to read the packet filter configuration
+ * from the temporary file named by the environmental variable pf_file.  This
+ * file may be generated asynchronously and may be dynamically updated during the
+ * client session, however the client will be blocked from sending or receiving
+ * VPN tunnel packets until the packet filter file has been generated.  OpenVPN
+ * will periodically test the packet filter file over the life of the client
+ * instance and reload when modified.  OpenVPN will delete the packet filter file
+ * when the client instance goes out of scope.
+ *
+ * Packet filter file grammar:
+ *
+ * [CLIENTS DROP|ACCEPT]
+ * {+|-}common_name1
+ * {+|-}common_name2
+ * . . .
+ * [SUBNETS DROP|ACCEPT]
+ * {+|-}subnet1
+ * {+|-}subnet2
+ * . . .
+ * [END]
+ *
+ * Subnet: IP-ADDRESS | IP-ADDRESS/NUM_NETWORK_BITS
+ *
+ * CLIENTS refers to the set of clients (by their common-name) which
+ * this instance is allowed ('+') to connect to, or is excluded ('-')
+ * from connecting to.  Note that in the case of client-to-client
+ * connections, such communication must be allowed by the packet filter
+ * configuration files of both clients.
+ *
+ * SUBNETS refers to IP addresses or IP address subnets which this
+ * instance may connect to ('+') or is excluded ('-') from connecting
+ * to.
+ *
+ * DROP or ACCEPT defines default policy when there is no explicit match
+ * for a common-name or subnet.  The [END] tag must exist.  A special
+ * purpose tag called [KILL] will immediately kill the client instance.
+ * A given client or subnet rule applies to both incoming and outgoing
+ * packets.
+ *
+ * See plugin/defer/simple.c for an example on using asynchronous
+ * authentication and client-specific packet filtering.
+ */
+OPENVPN_PLUGIN_DEF int OPENVPN_PLUGIN_FUNC(openvpn_plugin_func_v3)
+     (struct openvpn_plugin_args_func const *arguments,
+      openvpn_plugin_handle_t handle,
+      struct openvpn_plugin_string_list **return_list);
+
 /*
  * FUNCTION: openvpn_plugin_close_v1
  *
plugin.c +4 -2
index d04c01d..dcc18fb 100644
@@ -232,8 +232,10 @@ plugin_init_item (struct plugin *p, const struct plugin_option *o)
 
   PLUGIN_SYM (open1, "openvpn_plugin_open_v1", 0);
   PLUGIN_SYM (open2, "openvpn_plugin_open_v2", 0);
+  PLUGIN_SYM (open3, "openvpn_plugin_open_v3", 0);
   PLUGIN_SYM (func1, "openvpn_plugin_func_v1", 0);
   PLUGIN_SYM (func2, "openvpn_plugin_func_v2", 0);
+  PLUGIN_SYM (func3, "openvpn_plugin_func_v3", 0);
   PLUGIN_SYM (close, "openvpn_plugin_close_v1", PLUGIN_SYMBOL_REQUIRED);
   PLUGIN_SYM (abort, "openvpn_plugin_abort_v1", 0);
   PLUGIN_SYM (client_constructor, "openvpn_plugin_client_constructor_v1", 0);
@@ -241,10 +243,10 @@ plugin_init_item (struct plugin *p, const struct plugin_option *o)
   PLUGIN_SYM (min_version_required, "openvpn_plugin_min_version_required_v1", 0);
   PLUGIN_SYM (initialization_point, "openvpn_plugin_select_initialization_point_v1", 0);
 
-  if (!p->open1 && !p->open2)
+  if (!p->open1 && !p->open2 && !p->open3)
     msg (M_FATAL, "PLUGIN: symbol openvpn_plugin_open_vX is undefined in plugin: %s", p->so_pathname);
 
-  if (!p->func1 && !p->func2)
+  if (!p->func1 && !p->func2 && !p->func3)
     msg (M_FATAL, "PLUGIN: symbol openvpn_plugin_func_vX is undefined in plugin: %s", p->so_pathname);
 
   /*
plugin.h +2 -0
index 02da000..2db0e14 100644
@@ -61,8 +61,10 @@ struct plugin {
 
   openvpn_plugin_open_v1 open1;
   openvpn_plugin_open_v2 open2;
+  openvpn_plugin_open_v3 open3;
   openvpn_plugin_func_v1 func1;
   openvpn_plugin_func_v2 func2;
+  openvpn_plugin_func_v3 func3;
   openvpn_plugin_close_v1 close;
   openvpn_plugin_abort_v1 abort;
   openvpn_plugin_client_constructor_v1 client_constructor;
Signature · 1 line
1.7.2.2
#2 lore raw

PATCH 2/3 Implement the core v3 plug-in function calls.

In reply to David Sommerseth

Let OpenVPN call the openvpn_plugin_open_v3() and openvpn_plugin_func_v3() plug-in functions if they exist in the plug-in.

---
 plugin.c |   17 +++++++++++++++--
 1 files changed, 15 insertions(+), 2 deletions(-)
plugin.c +15 -2
index dcc18fb..7d02c8b 100644
@@ -298,7 +298,13 @@ plugin_open_item (struct plugin *p,
       /*
        * Call the plugin initialization
        */
-      if (p->open2)
+      if (p->open3) {
+        struct openvpn_plugin_args_open args = { .version   = OPENVPN_PLUGIN_ARGS_APIVER,
+                                                 .type_mask = &p->plugin_type_mask,
+                                                 .argv      = o->argv,
+                                                 .envp      = envp };
+        p->plugin_handle = (*p->open3)(&args, retlist);
+      } else if (p->open2)
 	p->plugin_handle = (*p->open2)(&p->plugin_type_mask, o->argv, envp, retlist);
       else if (p->open1)
 	p->plugin_handle = (*p->open1)(&p->plugin_type_mask, o->argv, envp);
@@ -350,7 +356,14 @@ plugin_call_item (const struct plugin *p,
       /*
        * Call the plugin work function
        */
-      if (p->func2)
+      if (p->func3) {
+        struct openvpn_plugin_args_func args = { .version = OPENVPN_PLUGIN_ARGS_APIVER,
+                                                 .type    = type,
+                                                 .argv    = (const char **) a.argv,
+                                                 .envp    = envp,
+                                                 .per_client_context = per_client_context };
+        status = (*p->func3)(&args, p->plugin_handle, retlist);
+      } else if (p->func2)
 	status = (*p->func2)(p->plugin_handle, type, (const char **)a.argv, envp, per_client_context, retlist);
       else if (p->func1)
 	status = (*p->func1)(p->plugin_handle, type, (const char **)a.argv, envp);
Signature · 1 line
1.7.2.2
#3 lore raw

PATCH 3/3 Added a simple plug-in demonstrating the v3 plug-in API.

In reply to David Sommerseth

This plug-in can be tested by running an OpenVPN server like this:

 # ./openvpn --plugin plugin/examples/log_v3.so --dev tun \
             --server 192.168.240.0 255.255.255.0 --ca sample-keys/ca.crt \
             --cert sample-keys/server.crt --key sample-keys/server.key \
             --dh sample-keys/dh1024.pem

The client can be started like this:

 # ./openvpn --client --remote localhost --ca sample-keys/ca.crt \
             --cert sample-keys/client.crt --key sample-keys/client.key \
             --dev tun --nobind --auth-user-pass
---
 plugin/examples/log_v3.c |  188 ++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 188 insertions(+), 0 deletions(-)
 create mode 100644 plugin/examples/log_v3.c
plugin/examples/log_v3.c new file +188 -0
new file mode 100644
index 0000000..37cda5f
@@ -0,0 +1,188 @@
+/*
+ *  OpenVPN -- An application to securely tunnel IP networks
+ *             over a single TCP/UDP port, with support for SSL/TLS-based
+ *             session authentication and key exchange,
+ *             packet encryption, packet authentication, and
+ *             packet compression.
+ *
+ *  Copyright (C) 2002-2009 OpenVPN Technologies, Inc. <[email protected]...>
+ *  Copyright (C) 2010 David Sommerseth <[email protected]...>
+ *
+ *  This program is free software; you can redistribute it and/or modify
+ *  it under the terms of the GNU General Public License version 2
+ *  as published by the Free Software Foundation.
+ *
+ *  This program is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU General Public License for more details.
+ *
+ *  You should have received a copy of the GNU General Public License
+ *  along with this program (see the file COPYING included with this
+ *  distribution); if not, write to the Free Software Foundation, Inc.,
+ *  59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+ */
+
+/*
+ * This plugin is similar to simple.c, except it also logs extra information
+ * to stdout for every plugin method called by OpenVPN.  The only difference
+ * between this (log_v3.c) and log.c is that this module uses the v3 plug-in
+ * API.
+ *
+ * See the README file for build instructions.
+ */
+
+#include <stdio.h>
+#include <string.h>
+#include <stdlib.h>
+
+#include "openvpn-plugin.h"
+
+/*
+ * Our context, where we keep our state.
+ */
+struct plugin_context {
+  const char *username;
+  const char *password;
+};
+
+/*
+ * Given an environmental variable name, search
+ * the envp array for its value, returning it
+ * if found or NULL otherwise.
+ */
+static const char *
+get_env (const char *name, const char *envp[])
+{
+  if (envp)
+    {
+      int i;
+      const int namelen = strlen (name);
+      for (i = 0; envp[i]; ++i)
+	{
+	  if (!strncmp (envp[i], name, namelen))
+	    {
+	      const char *cp = envp[i] + namelen;
+	      if (*cp == '=')
+		return cp + 1;
+	    }
+	}
+    }
+  return NULL;
+}
+
+OPENVPN_EXPORT openvpn_plugin_handle_t
+openvpn_plugin_open_v3 (struct openvpn_plugin_args_open const *args, struct openvpn_plugin_string_list **ret_list)
+{
+  struct plugin_context *context;
+
+  /*
+   * Allocate our context
+   */
+  context = (struct plugin_context *) calloc (1, sizeof (struct plugin_context));
+
+  /*
+   * Set the username/password we will require.
+   */
+  context->username = "foo";
+  context->password = "bar";
+
+  /*
+   * Which callbacks to intercept.
+   */
+  *args->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;
+}
+
+void
+show (const int type, const char *argv[], const char *envp[])
+{
+  size_t i;
+  switch (type)
+    {
+    case OPENVPN_PLUGIN_UP:
+      printf ("OPENVPN_PLUGIN_UP\n");
+      break;
+    case OPENVPN_PLUGIN_DOWN:
+      printf ("OPENVPN_PLUGIN_DOWN\n");
+      break;
+    case OPENVPN_PLUGIN_ROUTE_UP:
+      printf ("OPENVPN_PLUGIN_ROUTE_UP\n");
+      break;
+    case OPENVPN_PLUGIN_IPCHANGE:
+      printf ("OPENVPN_PLUGIN_IPCHANGE\n");
+      break;
+    case OPENVPN_PLUGIN_TLS_VERIFY:
+      printf ("OPENVPN_PLUGIN_TLS_VERIFY\n");
+      break;
+    case OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY:
+      printf ("OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY\n");
+      break;
+    case OPENVPN_PLUGIN_CLIENT_CONNECT_V2:
+      printf ("OPENVPN_PLUGIN_CLIENT_CONNECT_V2\n");
+      break;
+    case OPENVPN_PLUGIN_CLIENT_DISCONNECT:
+      printf ("OPENVPN_PLUGIN_CLIENT_DISCONNECT\n");
+      break;
+    case OPENVPN_PLUGIN_LEARN_ADDRESS:
+      printf ("OPENVPN_PLUGIN_LEARN_ADDRESS\n");
+      break;
+    case OPENVPN_PLUGIN_TLS_FINAL:
+      printf ("OPENVPN_PLUGIN_TLS_FINAL\n");
+      break;
+    default:
+      printf ("OPENVPN_PLUGIN_?\n");
+      break;
+    }
+
+  printf ("ARGV\n");
+  for (i = 0; argv[i] != NULL; ++i)
+    printf ("%d '%s'\n", (int)i, argv[i]);
+
+  printf ("ENVP\n");
+  for (i = 0; envp[i] != NULL; ++i)
+    printf ("%d '%s'\n", (int)i, envp[i]);
+}
+
+OPENVPN_EXPORT int
+openvpn_plugin_func_v3 (struct openvpn_plugin_args_func const *args, openvpn_plugin_handle_t handle,
+                        struct openvpn_plugin_string_list **ret_list)
+{
+  struct plugin_context *context = (struct plugin_context *) handle;
+
+  show (args->type, args->argv, args->envp);
+
+  /* check entered username/password against what we require */
+  if (args->type == OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY)
+    {
+      /* get username/password from envp string array */
+      const char *username = get_env ("username", args->envp);
+      const char *password = get_env ("password", args->envp);
+
+      if (username && !strcmp (username, context->username)
+	  && password && !strcmp (password, context->password))
+	return OPENVPN_PLUGIN_FUNC_SUCCESS;
+      else
+	return OPENVPN_PLUGIN_FUNC_ERROR;
+    }
+  else
+    return OPENVPN_PLUGIN_FUNC_SUCCESS;
+}
+
+OPENVPN_EXPORT void
+openvpn_plugin_close_v1 (openvpn_plugin_handle_t handle)
+{
+  struct plugin_context *context = (struct plugin_context *) handle;
+  free (context);
+}
Signature · 1 line
1.7.2.2
#4 lore raw

Re: [Openvpn-devel] [PATCH 3/3] Added a simple plug-in demonstrating the v3 plug-in API.

Hi,

Quoted 7 lines · David Sommerseth

This plug-in can be tested by running an OpenVPN server like this:

 # ./openvpn --plugin plugin/examples/log_v3.so --dev tun \
             --server 192.168.240.0 255.255.255.0 --ca sample-keys/ca.crt \
             --cert sample-keys/server.crt --key sample-keys/server.key \
             --dh sample-keys/dh1024.pem
Quoted 5 lines

The client can be started like this:

 # ./openvpn --client --remote localhost --ca sample-keys/ca.crt \
             --cert sample-keys/client.crt --key sample-keys/client.key \
             --dev tun --nobind --auth-user-pass

You might want to take a look at t_cltsrv.sh and build a "make check" test script from there... verifying the expected output in the logfile after the test run...

gert

Signature · 4 lines
USENET is *not* the non-clickable part of WWW!
                                                           //www.muc.de/~gert/
Gert Doering - Munich, Germany                             [email protected]...
fax: +49-89-35655025                        [email protected]...