Ticket #15: openvpn-plugin.h

File openvpn-plugin.h, 15.9 KB (added by Emmanuel Bretelle, 11 years ago)

headers required to compile the plugin

Line 
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-2010 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_ACCOUNTING            12
101#define OPENVPN_PLUGIN_N                     13
102
103/*
104 * Build a mask out of a set of plug-in types.
105 */
106#define OPENVPN_PLUGIN_MASK(x) (1<<(x))
107
108/*
109 * A pointer to a plugin-defined object which contains
110 * the object state.
111 */
112typedef void *openvpn_plugin_handle_t;
113
114/*
115 * Return value for openvpn_plugin_func_v1 function
116 */
117#define OPENVPN_PLUGIN_FUNC_SUCCESS  0
118#define OPENVPN_PLUGIN_FUNC_ERROR    1
119#define OPENVPN_PLUGIN_FUNC_DEFERRED 2
120
121/*
122 * For Windows (needs to be modified for MSVC)
123 */
124#if defined(__MINGW32_VERSION) && !defined(OPENVPN_PLUGIN_H)
125# define OPENVPN_EXPORT __declspec(dllexport)
126#else
127# define OPENVPN_EXPORT
128#endif
129
130/*
131 * If OPENVPN_PLUGIN_H is defined, we know that we are being
132 * included in an OpenVPN compile, rather than a plugin compile.
133 */
134#ifdef OPENVPN_PLUGIN_H
135
136/*
137 * We are compiling OpenVPN.
138 */
139#define OPENVPN_PLUGIN_DEF        typedef
140#define OPENVPN_PLUGIN_FUNC(name) (*name)
141
142#else
143
144/*
145 * We are compiling plugin.
146 */
147#define OPENVPN_PLUGIN_DEF        OPENVPN_EXPORT
148#define OPENVPN_PLUGIN_FUNC(name) name
149
150#endif
151
152/*
153 * Used by openvpn_plugin_func to return structured
154 * data.  The plugin should allocate all structure
155 * instances, name strings, and value strings with
156 * malloc, since OpenVPN will assume that it
157 * can free the list by calling free() over the same.
158 */
159struct openvpn_plugin_string_list
160{
161  struct openvpn_plugin_string_list *next;
162  char *name;
163  char *value;
164};
165
166/*
167 * Multiple plugin modules can be cascaded, and modules can be
168 * used in tandem with scripts.  The order of operation is that
169 * the module func() functions are called in the order that
170 * the modules were specified in the config file.  If a script
171 * was specified as well, it will be called last.  If the
172 * return code of the module/script controls an authentication
173 * function (such as tls-verify or auth-user-pass-verify), then
174 * every module and script must return success (0) in order for
175 * the connection to be authenticated.
176 *
177 * Notes:
178 *
179 * Plugins which use a privilege-separation model (by forking in
180 * their initialization function before the main OpenVPN process
181 * downgrades root privileges and/or executes a chroot) must
182 * daemonize after a fork if the "daemon" environmental variable is
183 * set.  In addition, if the "daemon_log_redirect" variable is set,
184 * the plugin should preserve stdout/stderr across the daemon()
185 * syscall.  See the daemonize() function in plugin/auth-pam/auth-pam.c
186 * for an example.
187 */
188
189/*
190 * Prototypes for functions which OpenVPN plug-ins must define.
191 */
192
193/*
194 * FUNCTION: openvpn_plugin_open_v2
195 *
196 * REQUIRED: YES
197 *
198 * Called on initial plug-in load.  OpenVPN will preserve plug-in state
199 * across SIGUSR1 restarts but not across SIGHUP restarts.  A SIGHUP reset
200 * will cause the plugin to be closed and reopened.
201 *
202 * ARGUMENTS
203 *
204 * *type_mask : Set by OpenVPN to the logical OR of all script
205 *              types which this version of OpenVPN supports.  The plug-in
206 *              should set this value to the logical OR of all script types
207 *              which the plug-in wants to intercept.  For example, if the
208 *              script wants to intercept the client-connect and
209 *              client-disconnect script types:
210 *
211 *              *type_mask = OPENVPN_PLUGIN_MASK(OPENVPN_PLUGIN_CLIENT_CONNECT)
212 *                         | OPENVPN_PLUGIN_MASK(OPENVPN_PLUGIN_CLIENT_DISCONNECT)
213 *
214 * argv : a NULL-terminated array of options provided to the OpenVPN
215 *        "plug-in" directive.  argv[0] is the dynamic library pathname.
216 *
217 * envp : a NULL-terminated array of OpenVPN-set environmental
218 *        variables in "name=value" format.  Note that for security reasons,
219 *        these variables are not actually written to the "official"
220 *        environmental variable store of the process.
221 *
222 * return_list : used to return data back to OpenVPN.
223 *
224 * RETURN VALUE
225 *
226 * An openvpn_plugin_handle_t value on success, NULL on failure
227 */
228OPENVPN_PLUGIN_DEF openvpn_plugin_handle_t OPENVPN_PLUGIN_FUNC(openvpn_plugin_open_v2)
229     (unsigned int *type_mask,
230      const char *argv[],
231      const char *envp[],
232      struct openvpn_plugin_string_list **return_list);
233
234/*
235 * FUNCTION: openvpn_plugin_func_v2
236 *
237 * Called to perform the work of a given script type.
238 *
239 * REQUIRED: YES
240 *
241 * ARGUMENTS
242 *
243 * handle : the openvpn_plugin_handle_t value which was returned by
244 *          openvpn_plugin_open.
245 *
246 * type : one of the PLUGIN_x types
247 *
248 * argv : a NULL-terminated array of "command line" options which
249 *        would normally be passed to the script.  argv[0] is the dynamic
250 *        library pathname.
251 *
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.
256 *
257 * per_client_context : the per-client context pointer which was returned by
258 *        openvpn_plugin_client_constructor_v1, if defined.
259 *
260 * return_list : used to return data back to OpenVPN.
261 *
262 * RETURN VALUE
263 *
264 * OPENVPN_PLUGIN_FUNC_SUCCESS on success, OPENVPN_PLUGIN_FUNC_ERROR on failure
265 *
266 * In addition, OPENVPN_PLUGIN_FUNC_DEFERRED may be returned by
267 * OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY.  This enables asynchronous
268 * authentication where the plugin (or one of its agents) may indicate
269 * authentication success/failure some number of seconds after the return
270 * of the OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY handler by writing a single
271 * char to the file named by auth_control_file in the environmental variable
272 * list (envp).
273 *
274 * first char of auth_control_file:
275 * '0' -- indicates auth failure
276 * '1' -- indicates auth success
277 *
278 * OpenVPN will delete the auth_control_file after it goes out of scope.
279 *
280 * If an OPENVPN_PLUGIN_ENABLE_PF handler is defined and returns success
281 * for a particular client instance, packet filtering will be enabled for that
282 * instance.  OpenVPN will then attempt to read the packet filter configuration
283 * from the temporary file named by the environmental variable pf_file.  This
284 * file may be generated asynchronously and may be dynamically updated during the
285 * client session, however the client will be blocked from sending or receiving
286 * VPN tunnel packets until the packet filter file has been generated.  OpenVPN
287 * will periodically test the packet filter file over the life of the client
288 * instance and reload when modified.  OpenVPN will delete the packet filter file
289 * when the client instance goes out of scope.
290 *
291 * Packet filter file grammar:
292 *
293 * [CLIENTS DROP|ACCEPT]
294 * {+|-}common_name1
295 * {+|-}common_name2
296 * . . .
297 * [SUBNETS DROP|ACCEPT]
298 * {+|-}subnet1
299 * {+|-}subnet2
300 * . . .
301 * [END]
302 *
303 * Subnet: IP-ADDRESS | IP-ADDRESS/NUM_NETWORK_BITS
304 *
305 * CLIENTS refers to the set of clients (by their common-name) which
306 * this instance is allowed ('+') to connect to, or is excluded ('-')
307 * from connecting to.  Note that in the case of client-to-client
308 * connections, such communication must be allowed by the packet filter
309 * configuration files of both clients.
310 *
311 * SUBNETS refers to IP addresses or IP address subnets which this
312 * instance may connect to ('+') or is excluded ('-') from connecting
313 * to.
314 *
315 * DROP or ACCEPT defines default policy when there is no explicit match
316 * for a common-name or subnet.  The [END] tag must exist.  A special
317 * purpose tag called [KILL] will immediately kill the client instance.
318 * A given client or subnet rule applies to both incoming and outgoing
319 * packets.
320 *
321 * See plugin/defer/simple.c for an example on using asynchronous
322 * authentication and client-specific packet filtering.
323 */
324OPENVPN_PLUGIN_DEF int OPENVPN_PLUGIN_FUNC(openvpn_plugin_func_v2)
325     (openvpn_plugin_handle_t handle,
326      const int type,
327      const char *argv[],
328      const char *envp[],
329      void *per_client_context,
330      struct openvpn_plugin_string_list **return_list);
331
332/*
333 * FUNCTION: openvpn_plugin_close_v1
334 *
335 * REQUIRED: YES
336 *
337 * ARGUMENTS
338 *
339 * handle : the openvpn_plugin_handle_t value which was returned by
340 *          openvpn_plugin_open.
341 *
342 * Called immediately prior to plug-in unload.
343 */
344OPENVPN_PLUGIN_DEF void OPENVPN_PLUGIN_FUNC(openvpn_plugin_close_v1)
345     (openvpn_plugin_handle_t handle);
346
347/*
348 * FUNCTION: openvpn_plugin_abort_v1
349 *
350 * REQUIRED: NO
351 *
352 * ARGUMENTS
353 *
354 * handle : the openvpn_plugin_handle_t value which was returned by
355 *          openvpn_plugin_open.
356 *
357 * Called when OpenVPN is in the process of aborting due to a fatal error.
358 * Will only be called on an open context returned by a prior successful
359 * openvpn_plugin_open callback.
360 */
361OPENVPN_PLUGIN_DEF void OPENVPN_PLUGIN_FUNC(openvpn_plugin_abort_v1)
362     (openvpn_plugin_handle_t handle);
363
364/*
365 * FUNCTION: openvpn_plugin_client_constructor_v1
366 *
367 * Called to allocate a per-client memory region, which
368 * is then passed to the openvpn_plugin_func_v2 function.
369 * This function is called every time the OpenVPN server
370 * constructs a client instance object, which normally
371 * occurs when a session-initiating packet is received
372 * by a new client, even before the client has authenticated.
373 *
374 * This function should allocate the private memory needed
375 * by the plugin to track individual OpenVPN clients, and
376 * return a void * to this memory region.
377 *
378 * REQUIRED: NO
379 *
380 * ARGUMENTS
381 *
382 * handle : the openvpn_plugin_handle_t value which was returned by
383 *          openvpn_plugin_open.
384 *
385 * RETURN VALUE
386 *
387 * void * pointer to plugin's private per-client memory region, or NULL
388 * if no memory region is required.
389 */
390OPENVPN_PLUGIN_DEF void * OPENVPN_PLUGIN_FUNC(openvpn_plugin_client_constructor_v1)
391     (openvpn_plugin_handle_t handle);
392
393/*
394 * FUNCTION: openvpn_plugin_client_destructor_v1
395 *
396 * This function is called on client instance object destruction.
397 *
398 * REQUIRED: NO
399 *
400 * ARGUMENTS
401 *
402 * handle : the openvpn_plugin_handle_t value which was returned by
403 *          openvpn_plugin_open.
404 *
405 * per_client_context : the per-client context pointer which was returned by
406 *        openvpn_plugin_client_constructor_v1, if defined.
407 */
408OPENVPN_PLUGIN_DEF void OPENVPN_PLUGIN_FUNC(openvpn_plugin_client_destructor_v1)
409     (openvpn_plugin_handle_t handle, void *per_client_context);
410
411/*
412 * FUNCTION: openvpn_plugin_select_initialization_point_v1
413 *
414 * Several different points exist in OpenVPN's initialization sequence where
415 * the openvpn_plugin_open function can be called.  While the default is
416 * OPENVPN_PLUGIN_INIT_PRE_DAEMON, this function can be used to select a
417 * different initialization point.  For example, if your plugin needs to
418 * return configuration parameters to OpenVPN, use
419 * OPENVPN_PLUGIN_INIT_PRE_CONFIG_PARSE.
420 *
421 * REQUIRED: NO
422 *
423 * RETURN VALUE:
424 *
425 * An OPENVPN_PLUGIN_INIT_x value.
426 */
427#define OPENVPN_PLUGIN_INIT_PRE_CONFIG_PARSE 1
428#define OPENVPN_PLUGIN_INIT_PRE_DAEMON       2 /* default */
429#define OPENVPN_PLUGIN_INIT_POST_DAEMON      3
430#define OPENVPN_PLUGIN_INIT_POST_UID_CHANGE  4
431
432OPENVPN_PLUGIN_DEF int OPENVPN_PLUGIN_FUNC(openvpn_plugin_select_initialization_point_v1)
433     (void);
434
435/*
436 * FUNCTION: openvpn_plugin_min_version_required_v1
437 *
438 * This function is called by OpenVPN to query the minimum
439   plugin interface version number required by the plugin.
440 *
441 * REQUIRED: NO
442 *
443 * RETURN VALUE
444 *
445 * The minimum OpenVPN plugin interface version number necessary to support
446 * this plugin.
447 */
448OPENVPN_PLUGIN_DEF int OPENVPN_PLUGIN_FUNC(openvpn_plugin_min_version_required_v1)
449     (void);
450
451/*
452 * Deprecated functions which are still supported for backward compatibility.
453 */
454
455OPENVPN_PLUGIN_DEF openvpn_plugin_handle_t OPENVPN_PLUGIN_FUNC(openvpn_plugin_open_v1)
456     (unsigned int *type_mask,
457      const char *argv[],
458      const char *envp[]);
459
460OPENVPN_PLUGIN_DEF int OPENVPN_PLUGIN_FUNC(openvpn_plugin_func_v1)
461     (openvpn_plugin_handle_t handle, const int type, const char *argv[], const char *envp[]);