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
8 * Copyright (C) 2002-2010 OpenVPN Technologies, Inc. <sales@openvpn.net>
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.
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.
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
25 #include <openssl/x509v3.h>
27 #define OPENVPN_PLUGIN_VERSION 3
30 * Plug-in types. These types correspond to the set of script callbacks
31 * supported by OpenVPN.
33 * This is the general call sequence to expect when running in server mode:
35 * Initial Server Startup:
37 * FUNC: openvpn_plugin_open_v1
38 * FUNC: openvpn_plugin_client_constructor_v1 (this is the top-level "generic"
40 * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_UP
41 * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_ROUTE_UP
43 * New Client Connection:
45 * FUNC: openvpn_plugin_client_constructor_v1
46 * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_ENABLE_PF
47 * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_TLS_VERIFY (called once for every cert
48 * in the server chain)
49 * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY
50 * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_TLS_FINAL
51 * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_IPCHANGE
53 * [If OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY returned OPENVPN_PLUGIN_FUNC_DEFERRED,
54 * we don't proceed until authentication is verified via auth_control_file]
56 * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_CLIENT_CONNECT_V2
57 * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_LEARN_ADDRESS
59 * [Client session ensues]
61 * For each "TLS soft reset", according to reneg-sec option (or similar):
63 * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_ENABLE_PF
65 * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_TLS_VERIFY (called once for every cert
66 * in the server chain)
67 * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY
68 * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_TLS_FINAL
70 * [If OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY returned OPENVPN_PLUGIN_FUNC_DEFERRED,
71 * we expect that authentication is verified via auth_control_file within
72 * the number of seconds defined by the "hand-window" option. Data channel traffic
73 * will continue to flow uninterrupted during this period.]
75 * [Client session continues]
77 * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_CLIENT_DISCONNECT
78 * FUNC: openvpn_plugin_client_destructor_v1
80 * [ some time may pass ]
82 * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_LEARN_ADDRESS (this coincides with a
83 * lazy free of initial
84 * learned addr object)
87 * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_DOWN
88 * FUNC: openvpn_plugin_client_destructor_v1 (top-level "generic" client)
89 * FUNC: openvpn_plugin_close_v1
91 #define OPENVPN_PLUGIN_UP 0
92 #define OPENVPN_PLUGIN_DOWN 1
93 #define OPENVPN_PLUGIN_ROUTE_UP 2
94 #define OPENVPN_PLUGIN_IPCHANGE 3
95 #define OPENVPN_PLUGIN_TLS_VERIFY 4
96 #define OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY 5
97 #define OPENVPN_PLUGIN_CLIENT_CONNECT 6
98 #define OPENVPN_PLUGIN_CLIENT_DISCONNECT 7
99 #define OPENVPN_PLUGIN_LEARN_ADDRESS 8
100 #define OPENVPN_PLUGIN_CLIENT_CONNECT_V2 9
101 #define OPENVPN_PLUGIN_TLS_FINAL 10
102 #define OPENVPN_PLUGIN_ENABLE_PF 11
103 #define OPENVPN_PLUGIN_N 12
106 * Build a mask out of a set of plug-in types.
108 #define OPENVPN_PLUGIN_MASK(x) (1<<(x))
111 * A pointer to a plugin-defined object which contains
114 typedef void *openvpn_plugin_handle_t;
117 * Return value for openvpn_plugin_func_v1 function
119 #define OPENVPN_PLUGIN_FUNC_SUCCESS 0
120 #define OPENVPN_PLUGIN_FUNC_ERROR 1
121 #define OPENVPN_PLUGIN_FUNC_DEFERRED 2
124 * For Windows (needs to be modified for MSVC)
126 #if defined(__MINGW32_VERSION) && !defined(OPENVPN_PLUGIN_H)
127 # define OPENVPN_EXPORT __declspec(dllexport)
129 # define OPENVPN_EXPORT
133 * If OPENVPN_PLUGIN_H is defined, we know that we are being
134 * included in an OpenVPN compile, rather than a plugin compile.
136 #ifdef OPENVPN_PLUGIN_H
139 * We are compiling OpenVPN.
141 #define OPENVPN_PLUGIN_DEF typedef
142 #define OPENVPN_PLUGIN_FUNC(name) (*name)
147 * We are compiling plugin.
149 #define OPENVPN_PLUGIN_DEF OPENVPN_EXPORT
150 #define OPENVPN_PLUGIN_FUNC(name) name
155 * Used by openvpn_plugin_func to return structured
156 * data. The plugin should allocate all structure
157 * instances, name strings, and value strings with
158 * malloc, since OpenVPN will assume that it
159 * can free the list by calling free() over the same.
161 struct openvpn_plugin_string_list
163 struct openvpn_plugin_string_list *next;
169 /* openvpn_plugin_{open,func}_v3() related structs */
171 /* Defines version of the v3 plugin argument structs
173 * Whenever one or more of these structs are modified, this constant
174 * must be updated. A changelog should be appended in this comment
175 * as well, to make it easier to see what information is available
176 * in the different versions.
179 * 1 Initial plugin v3 structures providing the same API as
180 * the v2 plugin interface + X509 certificate information.
183 #define OPENVPN_PLUGINv3_STRUCTVER 1
186 * Arguments used to transport variables to the plug-in.
187 * The struct openvpn_plugin_args_open_in is only used
188 * by the openvpn_plugin_open_v3() function.
192 * type_mask : Set by OpenVPN to the logical OR of all script
193 * types which this version of OpenVPN supports.
195 * argv : a NULL-terminated array of options provided to the OpenVPN
196 * "plug-in" directive. argv[0] is the dynamic library pathname.
198 * envp : a NULL-terminated array of OpenVPN-set environmental
199 * variables in "name=value" format. Note that for security reasons,
200 * these variables are not actually written to the "official"
201 * environmental variable store of the process.
203 struct openvpn_plugin_args_open_in
206 const char ** const argv;
207 const char ** const envp;
212 * Arguments used to transport variables from the plug-in back
213 * to the OpenVPN process. The struct openvpn_plugin_args_open_return
214 * is only used by the openvpn_plugin_open_v3() function.
218 * *type_mask : The plug-in should set this value to the logical OR of all script
219 * types which the plug-in wants to intercept. For example, if the
220 * script wants to intercept the client-connect and client-disconnect
223 * *type_mask = OPENVPN_PLUGIN_MASK(OPENVPN_PLUGIN_CLIENT_CONNECT)
224 * | OPENVPN_PLUGIN_MASK(OPENVPN_PLUGIN_CLIENT_DISCONNECT)
226 * *handle : Pointer to a global plug-in context, created by the plug-in. This pointer
227 * is passed on to the other plug-in calls.
229 * return_list : used to return data back to OpenVPN.
232 struct openvpn_plugin_args_open_return
235 openvpn_plugin_handle_t *handle;
236 struct openvpn_plugin_string_list **return_list;
240 * Arguments used to transport variables to and from the
241 * plug-in. The struct openvpn_plugin_args_func is only used
242 * by the openvpn_plugin_func_v3() function.
246 * type : one of the PLUGIN_x types.
248 * argv : a NULL-terminated array of "command line" options which
249 * would normally be passed to the script. argv[0] is the dynamic
252 * envp : a NULL-terminated array of OpenVPN-set environmental
253 * variables in "name=value" format. Note that for security reasons,
254 * these variables are not actually written to the "official"
255 * environmental variable store of the process.
257 * *handle : Pointer to a global plug-in context, created by the plug-in's openvpn_plugin_open_v3().
259 * *per_client_context : the per-client context pointer which was returned by
260 * openvpn_plugin_client_constructor_v1, if defined.
262 * current_cert_depth : Certificate depth of the certificate being passed over
264 * *current_cert : X509 Certificate object received from the client
267 struct openvpn_plugin_args_func_in
270 const char ** const argv;
271 const char ** const envp;
272 openvpn_plugin_handle_t handle;
273 void *per_client_context;
274 int current_cert_depth;
280 * Arguments used to transport variables to and from the
281 * plug-in. The struct openvpn_plugin_args_func is only used
282 * by the openvpn_plugin_func_v3() function.
286 * return_list : used to return data back to OpenVPN for further processing/usage by
287 * the OpenVPN executable.
290 struct openvpn_plugin_args_func_return
292 struct openvpn_plugin_string_list **return_list;
296 * Multiple plugin modules can be cascaded, and modules can be
297 * used in tandem with scripts. The order of operation is that
298 * the module func() functions are called in the order that
299 * the modules were specified in the config file. If a script
300 * was specified as well, it will be called last. If the
301 * return code of the module/script controls an authentication
302 * function (such as tls-verify or auth-user-pass-verify), then
303 * every module and script must return success (0) in order for
304 * the connection to be authenticated.
308 * Plugins which use a privilege-separation model (by forking in
309 * their initialization function before the main OpenVPN process
310 * downgrades root privileges and/or executes a chroot) must
311 * daemonize after a fork if the "daemon" environmental variable is
312 * set. In addition, if the "daemon_log_redirect" variable is set,
313 * the plugin should preserve stdout/stderr across the daemon()
314 * syscall. See the daemonize() function in plugin/auth-pam/auth-pam.c
319 * Prototypes for functions which OpenVPN plug-ins must define.
323 * FUNCTION: openvpn_plugin_open_v2
327 * Called on initial plug-in load. OpenVPN will preserve plug-in state
328 * across SIGUSR1 restarts but not across SIGHUP restarts. A SIGHUP reset
329 * will cause the plugin to be closed and reopened.
333 * *type_mask : Set by OpenVPN to the logical OR of all script
334 * types which this version of OpenVPN supports. The plug-in
335 * should set this value to the logical OR of all script types
336 * which the plug-in wants to intercept. For example, if the
337 * script wants to intercept the client-connect and
338 * client-disconnect script types:
340 * *type_mask = OPENVPN_PLUGIN_MASK(OPENVPN_PLUGIN_CLIENT_CONNECT)
341 * | OPENVPN_PLUGIN_MASK(OPENVPN_PLUGIN_CLIENT_DISCONNECT)
343 * argv : a NULL-terminated array of options provided to the OpenVPN
344 * "plug-in" directive. argv[0] is the dynamic library pathname.
346 * envp : a NULL-terminated array of OpenVPN-set environmental
347 * variables in "name=value" format. Note that for security reasons,
348 * these variables are not actually written to the "official"
349 * environmental variable store of the process.
351 * return_list : used to return data back to OpenVPN.
355 * An openvpn_plugin_handle_t value on success, NULL on failure
357 OPENVPN_PLUGIN_DEF openvpn_plugin_handle_t OPENVPN_PLUGIN_FUNC(openvpn_plugin_open_v2)
358 (unsigned int *type_mask,
361 struct openvpn_plugin_string_list **return_list);
364 * FUNCTION: openvpn_plugin_func_v2
366 * Called to perform the work of a given script type.
372 * handle : the openvpn_plugin_handle_t value which was returned by
373 * openvpn_plugin_open.
375 * type : one of the PLUGIN_x types
377 * argv : a NULL-terminated array of "command line" options which
378 * would normally be passed to the script. argv[0] is the dynamic
381 * envp : a NULL-terminated array of OpenVPN-set environmental
382 * variables in "name=value" format. Note that for security reasons,
383 * these variables are not actually written to the "official"
384 * environmental variable store of the process.
386 * per_client_context : the per-client context pointer which was returned by
387 * openvpn_plugin_client_constructor_v1, if defined.
389 * return_list : used to return data back to OpenVPN.
393 * OPENVPN_PLUGIN_FUNC_SUCCESS on success, OPENVPN_PLUGIN_FUNC_ERROR on failure
395 * In addition, OPENVPN_PLUGIN_FUNC_DEFERRED may be returned by
396 * OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY. This enables asynchronous
397 * authentication where the plugin (or one of its agents) may indicate
398 * authentication success/failure some number of seconds after the return
399 * of the OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY handler by writing a single
400 * char to the file named by auth_control_file in the environmental variable
403 * first char of auth_control_file:
404 * '0' -- indicates auth failure
405 * '1' -- indicates auth success
407 * OpenVPN will delete the auth_control_file after it goes out of scope.
409 * If an OPENVPN_PLUGIN_ENABLE_PF handler is defined and returns success
410 * for a particular client instance, packet filtering will be enabled for that
411 * instance. OpenVPN will then attempt to read the packet filter configuration
412 * from the temporary file named by the environmental variable pf_file. This
413 * file may be generated asynchronously and may be dynamically updated during the
414 * client session, however the client will be blocked from sending or receiving
415 * VPN tunnel packets until the packet filter file has been generated. OpenVPN
416 * will periodically test the packet filter file over the life of the client
417 * instance and reload when modified. OpenVPN will delete the packet filter file
418 * when the client instance goes out of scope.
420 * Packet filter file grammar:
422 * [CLIENTS DROP|ACCEPT]
426 * [SUBNETS DROP|ACCEPT]
432 * Subnet: IP-ADDRESS | IP-ADDRESS/NUM_NETWORK_BITS
434 * CLIENTS refers to the set of clients (by their common-name) which
435 * this instance is allowed ('+') to connect to, or is excluded ('-')
436 * from connecting to. Note that in the case of client-to-client
437 * connections, such communication must be allowed by the packet filter
438 * configuration files of both clients.
440 * SUBNETS refers to IP addresses or IP address subnets which this
441 * instance may connect to ('+') or is excluded ('-') from connecting
444 * DROP or ACCEPT defines default policy when there is no explicit match
445 * for a common-name or subnet. The [END] tag must exist. A special
446 * purpose tag called [KILL] will immediately kill the client instance.
447 * A given client or subnet rule applies to both incoming and outgoing
450 * See plugin/defer/simple.c for an example on using asynchronous
451 * authentication and client-specific packet filtering.
453 OPENVPN_PLUGIN_DEF int OPENVPN_PLUGIN_FUNC(openvpn_plugin_func_v2)
454 (openvpn_plugin_handle_t handle,
458 void *per_client_context,
459 struct openvpn_plugin_string_list **return_list);
463 * FUNCTION: openvpn_plugin_open_v3
467 * Called on initial plug-in load. OpenVPN will preserve plug-in state
468 * across SIGUSR1 restarts but not across SIGHUP restarts. A SIGHUP reset
469 * will cause the plugin to be closed and reopened.
473 * version : fixed value, defines the API version of the OpenVPN plug-in API. The plug-in
474 * should validate that this value is matching the OPENVPN_PLUGIN_VERSION value.
476 * arguments : Structure with all arguments available to the plug-in.
478 * retptr : used to return data back to OpenVPN.
482 * OPENVPN_PLUGIN_FUNC_SUCCESS on success, OPENVPN_PLUGIN_FUNC_ERROR on failure
484 OPENVPN_PLUGIN_DEF int OPENVPN_PLUGIN_FUNC(openvpn_plugin_open_v3)
486 struct openvpn_plugin_args_open_in const *arguments,
487 struct openvpn_plugin_args_open_return *retptr);
490 * FUNCTION: openvpn_plugin_func_v3
492 * Called to perform the work of a given script type.
498 * version : fixed value, defines the API version of the OpenVPN plug-in API. The plug-in
499 * should validate that this value is matching the OPENVPN_PLUGIN_VERSION value.
501 * handle : the openvpn_plugin_handle_t value which was returned by
502 * openvpn_plugin_open.
504 * return_list : used to return data back to OpenVPN.
508 * OPENVPN_PLUGIN_FUNC_SUCCESS on success, OPENVPN_PLUGIN_FUNC_ERROR on failure
510 * In addition, OPENVPN_PLUGIN_FUNC_DEFERRED may be returned by
511 * OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY. This enables asynchronous
512 * authentication where the plugin (or one of its agents) may indicate
513 * authentication success/failure some number of seconds after the return
514 * of the OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY handler by writing a single
515 * char to the file named by auth_control_file in the environmental variable
518 * first char of auth_control_file:
519 * '0' -- indicates auth failure
520 * '1' -- indicates auth success
522 * OpenVPN will delete the auth_control_file after it goes out of scope.
524 * If an OPENVPN_PLUGIN_ENABLE_PF handler is defined and returns success
525 * for a particular client instance, packet filtering will be enabled for that
526 * instance. OpenVPN will then attempt to read the packet filter configuration
527 * from the temporary file named by the environmental variable pf_file. This
528 * file may be generated asynchronously and may be dynamically updated during the
529 * client session, however the client will be blocked from sending or receiving
530 * VPN tunnel packets until the packet filter file has been generated. OpenVPN
531 * will periodically test the packet filter file over the life of the client
532 * instance and reload when modified. OpenVPN will delete the packet filter file
533 * when the client instance goes out of scope.
535 * Packet filter file grammar:
537 * [CLIENTS DROP|ACCEPT]
541 * [SUBNETS DROP|ACCEPT]
547 * Subnet: IP-ADDRESS | IP-ADDRESS/NUM_NETWORK_BITS
549 * CLIENTS refers to the set of clients (by their common-name) which
550 * this instance is allowed ('+') to connect to, or is excluded ('-')
551 * from connecting to. Note that in the case of client-to-client
552 * connections, such communication must be allowed by the packet filter
553 * configuration files of both clients.
555 * SUBNETS refers to IP addresses or IP address subnets which this
556 * instance may connect to ('+') or is excluded ('-') from connecting
559 * DROP or ACCEPT defines default policy when there is no explicit match
560 * for a common-name or subnet. The [END] tag must exist. A special
561 * purpose tag called [KILL] will immediately kill the client instance.
562 * A given client or subnet rule applies to both incoming and outgoing
565 * See plugin/defer/simple.c for an example on using asynchronous
566 * authentication and client-specific packet filtering.
568 OPENVPN_PLUGIN_DEF int OPENVPN_PLUGIN_FUNC(openvpn_plugin_func_v3)
570 struct openvpn_plugin_args_func_in const *arguments,
571 struct openvpn_plugin_args_func_return *retptr);
574 * FUNCTION: openvpn_plugin_close_v1
580 * handle : the openvpn_plugin_handle_t value which was returned by
581 * openvpn_plugin_open.
583 * Called immediately prior to plug-in unload.
585 OPENVPN_PLUGIN_DEF void OPENVPN_PLUGIN_FUNC(openvpn_plugin_close_v1)
586 (openvpn_plugin_handle_t handle);
589 * FUNCTION: openvpn_plugin_abort_v1
595 * handle : the openvpn_plugin_handle_t value which was returned by
596 * openvpn_plugin_open.
598 * Called when OpenVPN is in the process of aborting due to a fatal error.
599 * Will only be called on an open context returned by a prior successful
600 * openvpn_plugin_open callback.
602 OPENVPN_PLUGIN_DEF void OPENVPN_PLUGIN_FUNC(openvpn_plugin_abort_v1)
603 (openvpn_plugin_handle_t handle);
606 * FUNCTION: openvpn_plugin_client_constructor_v1
608 * Called to allocate a per-client memory region, which
609 * is then passed to the openvpn_plugin_func_v2 function.
610 * This function is called every time the OpenVPN server
611 * constructs a client instance object, which normally
612 * occurs when a session-initiating packet is received
613 * by a new client, even before the client has authenticated.
615 * This function should allocate the private memory needed
616 * by the plugin to track individual OpenVPN clients, and
617 * return a void * to this memory region.
623 * handle : the openvpn_plugin_handle_t value which was returned by
624 * openvpn_plugin_open.
628 * void * pointer to plugin's private per-client memory region, or NULL
629 * if no memory region is required.
631 OPENVPN_PLUGIN_DEF void * OPENVPN_PLUGIN_FUNC(openvpn_plugin_client_constructor_v1)
632 (openvpn_plugin_handle_t handle);
635 * FUNCTION: openvpn_plugin_client_destructor_v1
637 * This function is called on client instance object destruction.
643 * handle : the openvpn_plugin_handle_t value which was returned by
644 * openvpn_plugin_open.
646 * per_client_context : the per-client context pointer which was returned by
647 * openvpn_plugin_client_constructor_v1, if defined.
649 OPENVPN_PLUGIN_DEF void OPENVPN_PLUGIN_FUNC(openvpn_plugin_client_destructor_v1)
650 (openvpn_plugin_handle_t handle, void *per_client_context);
653 * FUNCTION: openvpn_plugin_select_initialization_point_v1
655 * Several different points exist in OpenVPN's initialization sequence where
656 * the openvpn_plugin_open function can be called. While the default is
657 * OPENVPN_PLUGIN_INIT_PRE_DAEMON, this function can be used to select a
658 * different initialization point. For example, if your plugin needs to
659 * return configuration parameters to OpenVPN, use
660 * OPENVPN_PLUGIN_INIT_PRE_CONFIG_PARSE.
666 * An OPENVPN_PLUGIN_INIT_x value.
668 #define OPENVPN_PLUGIN_INIT_PRE_CONFIG_PARSE 1
669 #define OPENVPN_PLUGIN_INIT_PRE_DAEMON 2 /* default */
670 #define OPENVPN_PLUGIN_INIT_POST_DAEMON 3
671 #define OPENVPN_PLUGIN_INIT_POST_UID_CHANGE 4
673 OPENVPN_PLUGIN_DEF int OPENVPN_PLUGIN_FUNC(openvpn_plugin_select_initialization_point_v1)
677 * FUNCTION: openvpn_plugin_min_version_required_v1
679 * This function is called by OpenVPN to query the minimum
680 plugin interface version number required by the plugin.
686 * The minimum OpenVPN plugin interface version number necessary to support
689 OPENVPN_PLUGIN_DEF int OPENVPN_PLUGIN_FUNC(openvpn_plugin_min_version_required_v1)
693 * Deprecated functions which are still supported for backward compatibility.
696 OPENVPN_PLUGIN_DEF openvpn_plugin_handle_t OPENVPN_PLUGIN_FUNC(openvpn_plugin_open_v1)
697 (unsigned int *type_mask,
701 OPENVPN_PLUGIN_DEF int OPENVPN_PLUGIN_FUNC(openvpn_plugin_func_v1)
702 (openvpn_plugin_handle_t handle, const int type, const char *argv[], const char *envp[]);