New OpenVPN plug-in API
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
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
@@ -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_listchar *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
@@ -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
@@ -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
PATCH 2/3 Implement the core v3 plug-in function calls.
In reply to David SommersethLet 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
@@ -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
PATCH 3/3 Added a simple plug-in demonstrating the v3 plug-in API.
In reply to David SommersethThis 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.pemThe 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
@@ -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
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]...