cosmetics
[tomato.git] / release / src / router / openvpn / openvpn-plugin.h
blobac683f2f80e053cccbac4c9153bb1888d174d65a
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.
8 * Copyright (C) 2002-2009 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 #define OPENVPN_PLUGIN_VERSION 2
28 * Plug-in types. These types correspond to the set of script callbacks
29 * supported by OpenVPN.
31 * This is the general call sequence to expect when running in server mode:
33 * Initial Server Startup:
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
41 * New Client Connection:
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
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]
53 * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_CLIENT_CONNECT_V2
54 * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_LEARN_ADDRESS
56 * [Client session ensues]
58 * For each "TLS soft reset", according to reneg-sec option (or similar):
60 * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_ENABLE_PF
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
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.]
72 * [Client session continues]
74 * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_CLIENT_DISCONNECT
75 * FUNC: openvpn_plugin_client_constructor_v1
77 * [ some time may pass ]
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:
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
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
103 * Build a mask out of a set of plug-in types.
105 #define OPENVPN_PLUGIN_MASK(x) (1<<(x))
108 * A pointer to a plugin-defined object which contains
109 * the object state.
111 typedef void *openvpn_plugin_handle_t;
114 * Return value for openvpn_plugin_func_v1 function
116 #define OPENVPN_PLUGIN_FUNC_SUCCESS 0
117 #define OPENVPN_PLUGIN_FUNC_ERROR 1
118 #define OPENVPN_PLUGIN_FUNC_DEFERRED 2
121 * For Windows (needs to be modified for MSVC)
123 #if defined(__MINGW32_VERSION) && !defined(OPENVPN_PLUGIN_H)
124 # define OPENVPN_EXPORT __declspec(dllexport)
125 #else
126 # define OPENVPN_EXPORT
127 #endif
130 * If OPENVPN_PLUGIN_H is defined, we know that we are being
131 * included in an OpenVPN compile, rather than a plugin compile.
133 #ifdef OPENVPN_PLUGIN_H
136 * We are compiling OpenVPN.
138 #define OPENVPN_PLUGIN_DEF typedef
139 #define OPENVPN_PLUGIN_FUNC(name) (*name)
141 #else
144 * We are compiling plugin.
146 #define OPENVPN_PLUGIN_DEF OPENVPN_EXPORT
147 #define OPENVPN_PLUGIN_FUNC(name) name
149 #endif
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.
158 struct openvpn_plugin_string_list
160 struct openvpn_plugin_string_list *next;
161 char *name;
162 char *value;
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.
176 * Notes:
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.
189 * Prototypes for functions which OpenVPN plug-ins must define.
193 * FUNCTION: openvpn_plugin_open_v2
195 * REQUIRED: YES
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.
201 * ARGUMENTS
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:
210 * *type_mask = OPENVPN_PLUGIN_MASK(OPENVPN_PLUGIN_CLIENT_CONNECT)
211 * | OPENVPN_PLUGIN_MASK(OPENVPN_PLUGIN_CLIENT_DISCONNECT)
213 * argv : a NULL-terminated array of options provided to the OpenVPN
214 * "plug-in" directive. argv[0] is the dynamic library pathname.
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.
221 * return_list : used to return data back to OpenVPN.
223 * RETURN VALUE
225 * An openvpn_plugin_handle_t value on success, NULL on failure
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);
234 * FUNCTION: openvpn_plugin_func_v2
236 * Called to perform the work of a given script type.
238 * REQUIRED: YES
240 * ARGUMENTS
242 * handle : the openvpn_plugin_handle_t value which was returned by
243 * openvpn_plugin_open.
245 * type : one of the PLUGIN_x types
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.
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.
256 * per_client_context : the per-client context pointer which was returned by
257 * openvpn_plugin_client_constructor_v1, if defined.
259 * return_list : used to return data back to OpenVPN.
261 * RETURN VALUE
263 * OPENVPN_PLUGIN_FUNC_SUCCESS on success, OPENVPN_PLUGIN_FUNC_ERROR on failure
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).
273 * first char of auth_control_file:
274 * '0' -- indicates auth failure
275 * '1' -- indicates auth success
277 * OpenVPN will delete the auth_control_file after it goes out of scope.
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.
290 * Packet filter file grammar:
292 * [CLIENTS DROP|ACCEPT]
293 * {+|-}common_name1
294 * {+|-}common_name2
295 * . . .
296 * [SUBNETS DROP|ACCEPT]
297 * {+|-}subnet1
298 * {+|-}subnet2
299 * . . .
300 * [END]
302 * Subnet: IP-ADDRESS | IP-ADDRESS/NUM_NETWORK_BITS
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.
310 * SUBNETS refers to IP addresses or IP address subnets which this
311 * instance may connect to ('+') or is excluded ('-') from connecting
312 * to.
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.
320 * See plugin/defer/simple.c for an example on using asynchronous
321 * authentication and client-specific packet filtering.
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);
332 * FUNCTION: openvpn_plugin_close_v1
334 * REQUIRED: YES
336 * ARGUMENTS
338 * handle : the openvpn_plugin_handle_t value which was returned by
339 * openvpn_plugin_open.
341 * Called immediately prior to plug-in unload.
343 OPENVPN_PLUGIN_DEF void OPENVPN_PLUGIN_FUNC(openvpn_plugin_close_v1)
344 (openvpn_plugin_handle_t handle);
347 * FUNCTION: openvpn_plugin_abort_v1
349 * REQUIRED: NO
351 * ARGUMENTS
353 * handle : the openvpn_plugin_handle_t value which was returned by
354 * openvpn_plugin_open.
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.
360 OPENVPN_PLUGIN_DEF void OPENVPN_PLUGIN_FUNC(openvpn_plugin_abort_v1)
361 (openvpn_plugin_handle_t handle);
364 * FUNCTION: openvpn_plugin_client_constructor_v1
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.
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.
377 * REQUIRED: NO
379 * ARGUMENTS
381 * handle : the openvpn_plugin_handle_t value which was returned by
382 * openvpn_plugin_open.
384 * RETURN VALUE
386 * void * pointer to plugin's private per-client memory region, or NULL
387 * if no memory region is required.
389 OPENVPN_PLUGIN_DEF void * OPENVPN_PLUGIN_FUNC(openvpn_plugin_client_constructor_v1)
390 (openvpn_plugin_handle_t handle);
393 * FUNCTION: openvpn_plugin_client_destructor_v1
395 * This function is called on client instance object destruction.
397 * REQUIRED: NO
399 * ARGUMENTS
401 * handle : the openvpn_plugin_handle_t value which was returned by
402 * openvpn_plugin_open.
404 * per_client_context : the per-client context pointer which was returned by
405 * openvpn_plugin_client_constructor_v1, if defined.
407 OPENVPN_PLUGIN_DEF void OPENVPN_PLUGIN_FUNC(openvpn_plugin_client_destructor_v1)
408 (openvpn_plugin_handle_t handle, void *per_client_context);
411 * FUNCTION: openvpn_plugin_select_initialization_point_v1
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.
420 * REQUIRED: NO
422 * RETURN VALUE:
424 * An OPENVPN_PLUGIN_INIT_x value.
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
431 OPENVPN_PLUGIN_DEF int OPENVPN_PLUGIN_FUNC(openvpn_plugin_select_initialization_point_v1)
432 (void);
435 * FUNCTION: openvpn_plugin_min_version_required_v1
437 * This function is called by OpenVPN to query the minimum
438 plugin interface version number required by the plugin.
440 * REQUIRED: NO
442 * RETURN VALUE
444 * The minimum OpenVPN plugin interface version number necessary to support
445 * this plugin.
447 OPENVPN_PLUGIN_DEF int OPENVPN_PLUGIN_FUNC(openvpn_plugin_min_version_required_v1)
448 (void);
451 * Deprecated functions which are still supported for backward compatibility.
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[]);
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[]);