release/src/router/openvpn/openvpn-plugin.h

   1 /*
   2  *  OpenVPN -- An application to securely tunnel IP networks
   3  *             over a single TCP/UDP port, with support for SSL/TLS-based
   4  *             session authentication and key exchange,
   5  *             packet encryption, packet authentication, and
   6  *             packet compression.
   7  *
   8  *  Copyright (C) 2002-2009 OpenVPN Technologies, Inc. <sales@openvpn.net>
   9  *
  10  *  This program is free software; you can redistribute it and/or modify
  11  *  it under the terms of the GNU General Public License version 2
  12  *  as published by the Free Software Foundation.
  13  *
  14  *  This program is distributed in the hope that it will be useful,
  15  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17  *  GNU General Public License for more details.
  18  *
  19  *  You should have received a copy of the GNU General Public License
  20  *  along with this program (see the file COPYING included with this
  21  *  distribution); if not, write to the Free Software Foundation, Inc.,
  22  *  59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  23  */
  24
  25 #define OPENVPN_PLUGIN_VERSION 2
  26
  27 /*
  28  * Plug-in types.  These types correspond to the set of script callbacks
  29  * supported by OpenVPN.
  30  *
  31  * This is the general call sequence to expect when running in server mode:
  32  *
  33  * Initial Server Startup:
  34  *
  35  * FUNC: openvpn_plugin_open_v1
  36  * FUNC: openvpn_plugin_client_constructor_v1 (this is the top-level "generic"
  37  *                                             client template)
  38  * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_UP
  39  * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_ROUTE_UP
  40  *
  41  * New Client Connection:
  42  *
  43  * FUNC: openvpn_plugin_client_constructor_v1
  44  * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_TLS_VERIFY (called once for every cert
  45  *                                                     in the server chain)
  46  * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY
  47  * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_TLS_FINAL
  48  * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_IPCHANGE
  49  *
  50  * [If OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY returned OPENVPN_PLUGIN_FUNC_DEFERRED,
  51  * we don't proceed until authentication is verified via auth_control_file]
  52  *
  53  * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_CLIENT_CONNECT_V2
  54  * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_LEARN_ADDRESS
  55  *
  56  * [Client session ensues]
  57  *
  58  * For each "TLS soft reset", according to reneg-sec option (or similar):
  59  *
  60  * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_ENABLE_PF
  61  *
  62  * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_TLS_VERIFY (called once for every cert
  63  *                                                     in the server chain)
  64  * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY
  65  * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_TLS_FINAL
  66  *
  67  * [If OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY returned OPENVPN_PLUGIN_FUNC_DEFERRED,
  68  * we expect that authentication is verified via auth_control_file within
  69  * the number of seconds defined by the "hand-window" option.  Data channel traffic
  70  * will continue to flow uninterrupted during this period.]
  71  *
  72  * [Client session continues]
  73  *
  74  * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_CLIENT_DISCONNECT
  75  * FUNC: openvpn_plugin_client_constructor_v1
  76  *
  77  * [ some time may pass ]
  78  *
  79  * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_LEARN_ADDRESS (this coincides with a
  80  *                                                            lazy free of initial
  81  *                                                            learned addr object)
  82  * Server Shutdown:
  83  *
  84  * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_DOWN
  85  * FUNC: openvpn_plugin_client_destructor_v1 (top-level "generic" client)
  86  * FUNC: openvpn_plugin_close_v1
  87  */
  88 #define OPENVPN_PLUGIN_UP                    0
  89 #define OPENVPN_PLUGIN_DOWN                  1
  90 #define OPENVPN_PLUGIN_ROUTE_UP              2
  91 #define OPENVPN_PLUGIN_IPCHANGE              3
  92 #define OPENVPN_PLUGIN_TLS_VERIFY            4
  93 #define OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY 5
  94 #define OPENVPN_PLUGIN_CLIENT_CONNECT        6
  95 #define OPENVPN_PLUGIN_CLIENT_DISCONNECT     7
  96 #define OPENVPN_PLUGIN_LEARN_ADDRESS         8
  97 #define OPENVPN_PLUGIN_CLIENT_CONNECT_V2     9
  98 #define OPENVPN_PLUGIN_TLS_FINAL             10
  99 #define OPENVPN_PLUGIN_ENABLE_PF             11
 100 #define OPENVPN_PLUGIN_N                     12
 101
 102 /*
 103  * Build a mask out of a set of plug-in types.
 104  */
 105 #define OPENVPN_PLUGIN_MASK(x) (1<<(x))
 106
 107 /*
 108  * A pointer to a plugin-defined object which contains
 109  * the object state.
 110  */
 111 typedef void *openvpn_plugin_handle_t;
 112
 113 /*
 114  * Return value for openvpn_plugin_func_v1 function
 115  */
 116 #define OPENVPN_PLUGIN_FUNC_SUCCESS  0
 117 #define OPENVPN_PLUGIN_FUNC_ERROR    1
 118 #define OPENVPN_PLUGIN_FUNC_DEFERRED 2
 119
 120 /*
 121  * For Windows (needs to be modified for MSVC)
 122  */
 123 #if defined(__MINGW32_VERSION) && !defined(OPENVPN_PLUGIN_H)
 124 # define OPENVPN_EXPORT __declspec(dllexport)
 125 #else
 126 # define OPENVPN_EXPORT
 127 #endif
 128
 129 /*
 130  * If OPENVPN_PLUGIN_H is defined, we know that we are being
 131  * included in an OpenVPN compile, rather than a plugin compile.
 132  */
 133 #ifdef OPENVPN_PLUGIN_H
 134
 135 /*
 136  * We are compiling OpenVPN.
 137  */
 138 #define OPENVPN_PLUGIN_DEF        typedef
 139 #define OPENVPN_PLUGIN_FUNC(name) (*name)
 140
 141 #else
 142
 143 /*
 144  * We are compiling plugin.
 145  */
 146 #define OPENVPN_PLUGIN_DEF        OPENVPN_EXPORT
 147 #define OPENVPN_PLUGIN_FUNC(name) name
 148
 149 #endif
 150
 151 /*
 152  * Used by openvpn_plugin_func to return structured
 153  * data.  The plugin should allocate all structure
 154  * instances, name strings, and value strings with
 155  * malloc, since OpenVPN will assume that it
 156  * can free the list by calling free() over the same.
 157  */
 158 struct openvpn_plugin_string_list
 159 {
 160   struct openvpn_plugin_string_list *next;
 161   char *name;
 162   char *value;
 163 };
 164
 165 /*
 166  * Multiple plugin modules can be cascaded, and modules can be
 167  * used in tandem with scripts.  The order of operation is that
 168  * the module func() functions are called in the order that
 169  * the modules were specified in the config file.  If a script
 170  * was specified as well, it will be called last.  If the
 171  * return code of the module/script controls an authentication
 172  * function (such as tls-verify or auth-user-pass-verify), then
 173  * every module and script must return success (0) in order for
 174  * the connection to be authenticated.
 175  *
 176  * Notes:
 177  *
 178  * Plugins which use a privilege-separation model (by forking in
 179  * their initialization function before the main OpenVPN process
 180  * downgrades root privileges and/or executes a chroot) must
 181  * daemonize after a fork if the "daemon" environmental variable is
 182  * set.  In addition, if the "daemon_log_redirect" variable is set,
 183  * the plugin should preserve stdout/stderr across the daemon()
 184  * syscall.  See the daemonize() function in plugin/auth-pam/auth-pam.c
 185  * for an example.
 186  */
 187
 188 /*
 189  * Prototypes for functions which OpenVPN plug-ins must define.
 190  */
 191
 192 /*
 193  * FUNCTION: openvpn_plugin_open_v2
 194  *
 195  * REQUIRED: YES
 196  *
 197  * Called on initial plug-in load.  OpenVPN will preserve plug-in state
 198  * across SIGUSR1 restarts but not across SIGHUP restarts.  A SIGHUP reset
 199  * will cause the plugin to be closed and reopened.
 200  *
 201  * ARGUMENTS
 202  *
 203  * *type_mask : Set by OpenVPN to the logical OR of all script
 204  *              types which this version of OpenVPN supports.  The plug-in
 205  *              should set this value to the logical OR of all script types
 206  *              which the plug-in wants to intercept.  For example, if the
 207  *              script wants to intercept the client-connect and
 208  *              client-disconnect script types:
 209  *
 210  *              *type_mask = OPENVPN_PLUGIN_MASK(OPENVPN_PLUGIN_CLIENT_CONNECT)
 211  *                         | OPENVPN_PLUGIN_MASK(OPENVPN_PLUGIN_CLIENT_DISCONNECT)
 212  *
 213  * argv : a NULL-terminated array of options provided to the OpenVPN
 214  *        "plug-in" directive.  argv[0] is the dynamic library pathname.
 215  *
 216  * envp : a NULL-terminated array of OpenVPN-set environmental
 217  *        variables in "name=value" format.  Note that for security reasons,
 218  *        these variables are not actually written to the "official"
 219  *        environmental variable store of the process.
 220  *
 221  * return_list : used to return data back to OpenVPN.
 222  *
 223  * RETURN VALUE
 224  *
 225  * An openvpn_plugin_handle_t value on success, NULL on failure
 226  */
 227 OPENVPN_PLUGIN_DEF openvpn_plugin_handle_t OPENVPN_PLUGIN_FUNC(openvpn_plugin_open_v2)
 228      (unsigned int *type_mask,
 229       const char *argv[],
 230       const char *envp[],
 231       struct openvpn_plugin_string_list **return_list);
 232
 233 /*
 234  * FUNCTION: openvpn_plugin_func_v2
 235  *
 236  * Called to perform the work of a given script type.
 237  *
 238  * REQUIRED: YES
 239  *
 240  * ARGUMENTS
 241  *
 242  * handle : the openvpn_plugin_handle_t value which was returned by
 243  *          openvpn_plugin_open.
 244  *
 245  * type : one of the PLUGIN_x types
 246  *
 247  * argv : a NULL-terminated array of "command line" options which
 248  *        would normally be passed to the script.  argv[0] is the dynamic
 249  *        library pathname.
 250  *
 251  * envp : a NULL-terminated array of OpenVPN-set environmental
 252  *        variables in "name=value" format.  Note that for security reasons,
 253  *        these variables are not actually written to the "official"
 254  *        environmental variable store of the process.
 255  *
 256  * per_client_context : the per-client context pointer which was returned by
 257  *        openvpn_plugin_client_constructor_v1, if defined.
 258  *
 259  * return_list : used to return data back to OpenVPN.
 260  *
 261  * RETURN VALUE
 262  *
 263  * OPENVPN_PLUGIN_FUNC_SUCCESS on success, OPENVPN_PLUGIN_FUNC_ERROR on failure
 264  *
 265  * In addition, OPENVPN_PLUGIN_FUNC_DEFERRED may be returned by
 266  * OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY.  This enables asynchronous
 267  * authentication where the plugin (or one of its agents) may indicate
 268  * authentication success/failure some number of seconds after the return
 269  * of the OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY handler by writing a single
 270  * char to the file named by auth_control_file in the environmental variable
 271  * list (envp).
 272  *
 273  * first char of auth_control_file:
 274  * '0' -- indicates auth failure
 275  * '1' -- indicates auth success
 276  *
 277  * OpenVPN will delete the auth_control_file after it goes out of scope.
 278  *
 279  * If an OPENVPN_PLUGIN_ENABLE_PF handler is defined and returns success
 280  * for a particular client instance, packet filtering will be enabled for that
 281  * instance.  OpenVPN will then attempt to read the packet filter configuration
 282  * from the temporary file named by the environmental variable pf_file.  This
 283  * file may be generated asynchronously and may be dynamically updated during the
 284  * client session, however the client will be blocked from sending or receiving
 285  * VPN tunnel packets until the packet filter file has been generated.  OpenVPN
 286  * will periodically test the packet filter file over the life of the client
 287  * instance and reload when modified.  OpenVPN will delete the packet filter file
 288  * when the client instance goes out of scope.
 289  *
 290  * Packet filter file grammar:
 291  *
 292  * [CLIENTS DROP|ACCEPT]
 293  * {+|-}common_name1
 294  * {+|-}common_name2
 295  * . . .
 296  * [SUBNETS DROP|ACCEPT]
 297  * {+|-}subnet1
 298  * {+|-}subnet2
 299  * . . .
 300  * [END]
 301  *
 302  * Subnet: IP-ADDRESS | IP-ADDRESS/NUM_NETWORK_BITS
 303  *
 304  * CLIENTS refers to the set of clients (by their common-name) which
 305  * this instance is allowed ('+') to connect to, or is excluded ('-')
 306  * from connecting to.  Note that in the case of client-to-client
 307  * connections, such communication must be allowed by the packet filter
 308  * configuration files of both clients.
 309  *
 310  * SUBNETS refers to IP addresses or IP address subnets which this
 311  * instance may connect to ('+') or is excluded ('-') from connecting
 312  * to.
 313  *
 314  * DROP or ACCEPT defines default policy when there is no explicit match
 315  * for a common-name or subnet.  The [END] tag must exist.  A special
 316  * purpose tag called [KILL] will immediately kill the client instance.
 317  * A given client or subnet rule applies to both incoming and outgoing
 318  * packets.
 319  *
 320  * See plugin/defer/simple.c for an example on using asynchronous
 321  * authentication and client-specific packet filtering.
 322  */
 323 OPENVPN_PLUGIN_DEF int OPENVPN_PLUGIN_FUNC(openvpn_plugin_func_v2)
 324      (openvpn_plugin_handle_t handle,
 325       const int type,
 326       const char *argv[],
 327       const char *envp[],
 328       void *per_client_context,
 329       struct openvpn_plugin_string_list **return_list);
 330
 331 /*
 332  * FUNCTION: openvpn_plugin_close_v1
 333  *
 334  * REQUIRED: YES
 335  *
 336  * ARGUMENTS
 337  *
 338  * handle : the openvpn_plugin_handle_t value which was returned by
 339  *          openvpn_plugin_open.
 340  *
 341  * Called immediately prior to plug-in unload.
 342  */
 343 OPENVPN_PLUGIN_DEF void OPENVPN_PLUGIN_FUNC(openvpn_plugin_close_v1)
 344      (openvpn_plugin_handle_t handle);
 345
 346 /*
 347  * FUNCTION: openvpn_plugin_abort_v1
 348  *
 349  * REQUIRED: NO
 350  *
 351  * ARGUMENTS
 352  *
 353  * handle : the openvpn_plugin_handle_t value which was returned by
 354  *          openvpn_plugin_open.
 355  *
 356  * Called when OpenVPN is in the process of aborting due to a fatal error.
 357  * Will only be called on an open context returned by a prior successful
 358  * openvpn_plugin_open callback.
 359  */
 360 OPENVPN_PLUGIN_DEF void OPENVPN_PLUGIN_FUNC(openvpn_plugin_abort_v1)
 361      (openvpn_plugin_handle_t handle);
 362
 363 /*
 364  * FUNCTION: openvpn_plugin_client_constructor_v1
 365  *
 366  * Called to allocate a per-client memory region, which
 367  * is then passed to the openvpn_plugin_func_v2 function.
 368  * This function is called every time the OpenVPN server
 369  * constructs a client instance object, which normally
 370  * occurs when a session-initiating packet is received
 371  * by a new client, even before the client has authenticated.
 372  *
 373  * This function should allocate the private memory needed
 374  * by the plugin to track individual OpenVPN clients, and
 375  * return a void * to this memory region.
 376  *
 377  * REQUIRED: NO
 378  *
 379  * ARGUMENTS
 380  *
 381  * handle : the openvpn_plugin_handle_t value which was returned by
 382  *          openvpn_plugin_open.
 383  *
 384  * RETURN VALUE
 385  *
 386  * void * pointer to plugin's private per-client memory region, or NULL
 387  * if no memory region is required.
 388  */
 389 OPENVPN_PLUGIN_DEF void * OPENVPN_PLUGIN_FUNC(openvpn_plugin_client_constructor_v1)
 390      (openvpn_plugin_handle_t handle);
 391
 392 /*
 393  * FUNCTION: openvpn_plugin_client_destructor_v1
 394  *
 395  * This function is called on client instance object destruction.
 396  *
 397  * REQUIRED: NO
 398  *
 399  * ARGUMENTS
 400  *
 401  * handle : the openvpn_plugin_handle_t value which was returned by
 402  *          openvpn_plugin_open.
 403  *
 404  * per_client_context : the per-client context pointer which was returned by
 405  *        openvpn_plugin_client_constructor_v1, if defined.
 406  */
 407 OPENVPN_PLUGIN_DEF void OPENVPN_PLUGIN_FUNC(openvpn_plugin_client_destructor_v1)
 408      (openvpn_plugin_handle_t handle, void *per_client_context);
 409
 410 /*
 411  * FUNCTION: openvpn_plugin_select_initialization_point_v1
 412  *
 413  * Several different points exist in OpenVPN's initialization sequence where
 414  * the openvpn_plugin_open function can be called.  While the default is
 415  * OPENVPN_PLUGIN_INIT_PRE_DAEMON, this function can be used to select a
 416  * different initialization point.  For example, if your plugin needs to
 417  * return configuration parameters to OpenVPN, use
 418  * OPENVPN_PLUGIN_INIT_PRE_CONFIG_PARSE.
 419  *
 420  * REQUIRED: NO
 421  *
 422  * RETURN VALUE:
 423  *
 424  * An OPENVPN_PLUGIN_INIT_x value.
 425  */
 426 #define OPENVPN_PLUGIN_INIT_PRE_CONFIG_PARSE 1
 427 #define OPENVPN_PLUGIN_INIT_PRE_DAEMON       2 /* default */
 428 #define OPENVPN_PLUGIN_INIT_POST_DAEMON      3
 429 #define OPENVPN_PLUGIN_INIT_POST_UID_CHANGE  4
 430
 431 OPENVPN_PLUGIN_DEF int OPENVPN_PLUGIN_FUNC(openvpn_plugin_select_initialization_point_v1)
 432      (void);
 433
 434 /*
 435  * FUNCTION: openvpn_plugin_min_version_required_v1
 436  *
 437  * This function is called by OpenVPN to query the minimum
 438    plugin interface version number required by the plugin.
 439  *
 440  * REQUIRED: NO
 441  *
 442  * RETURN VALUE
 443  *
 444  * The minimum OpenVPN plugin interface version number necessary to support
 445  * this plugin.
 446  */
 447 OPENVPN_PLUGIN_DEF int OPENVPN_PLUGIN_FUNC(openvpn_plugin_min_version_required_v1)
 448      (void);
 449
 450 /*
 451  * Deprecated functions which are still supported for backward compatibility.
 452  */
 453
 454 OPENVPN_PLUGIN_DEF openvpn_plugin_handle_t OPENVPN_PLUGIN_FUNC(openvpn_plugin_open_v1)
 455      (unsigned int *type_mask,
 456       const char *argv[],
 457       const char *envp[]);
 458
 459 OPENVPN_PLUGIN_DEF int OPENVPN_PLUGIN_FUNC(openvpn_plugin_func_v1)
 460      (openvpn_plugin_handle_t handle, const int type, const char *argv[], const char *envp[]);