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#ifndef OPENVPN_PLUGIN_H_ 26#define OPENVPN_PLUGIN_H_ 27 28#define OPENVPN_PLUGIN_VERSION 3 29 30#ifdef ENABLE_SSL 31#ifdef ENABLE_CRYPTO_POLARSSL 32#include <polarssl/x509.h> 33#ifndef __OPENVPN_X509_CERT_T_DECLARED 34#define __OPENVPN_X509_CERT_T_DECLARED 35typedef x509_cert openvpn_x509_cert_t; 36#endif 37#else 38#include <openssl/x509.h> 39#ifndef __OPENVPN_X509_CERT_T_DECLARED 40#define __OPENVPN_X509_CERT_T_DECLARED 41typedef X509 openvpn_x509_cert_t; 42#endif 43#endif 44#endif 45 46#include <stdarg.h> 47 48#ifdef __cplusplus 49extern "C" { 50#endif 51 52/* 53 * Plug-in types. These types correspond to the set of script callbacks 54 * supported by OpenVPN. 55 * 56 * This is the general call sequence to expect when running in server mode: 57 * 58 * Initial Server Startup: 59 * 60 * FUNC: openvpn_plugin_open_v1 61 * FUNC: openvpn_plugin_client_constructor_v1 (this is the top-level "generic" 62 * client template) 63 * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_UP 64 * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_ROUTE_UP 65 * 66 * New Client Connection: 67 * 68 * FUNC: openvpn_plugin_client_constructor_v1 69 * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_ENABLE_PF 70 * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_TLS_VERIFY (called once for every cert 71 * in the server chain) 72 * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY 73 * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_TLS_FINAL 74 * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_IPCHANGE 75 * 76 * [If OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY returned OPENVPN_PLUGIN_FUNC_DEFERRED, 77 * we don't proceed until authentication is verified via auth_control_file] 78 * 79 * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_CLIENT_CONNECT_V2 80 * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_LEARN_ADDRESS 81 * 82 * [Client session ensues] 83 * 84 * For each "TLS soft reset", according to reneg-sec option (or similar): 85 * 86 * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_ENABLE_PF 87 * 88 * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_TLS_VERIFY (called once for every cert 89 * in the server chain) 90 * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY 91 * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_TLS_FINAL 92 * 93 * [If OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY returned OPENVPN_PLUGIN_FUNC_DEFERRED, 94 * we expect that authentication is verified via auth_control_file within 95 * the number of seconds defined by the "hand-window" option. Data channel traffic 96 * will continue to flow uninterrupted during this period.] 97 * 98 * [Client session continues] 99 * 100 * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_CLIENT_DISCONNECT 101 * FUNC: openvpn_plugin_client_destructor_v1 102 * 103 * [ some time may pass ] 104 * 105 * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_LEARN_ADDRESS (this coincides with a 106 * lazy free of initial 107 * learned addr object) 108 * Server Shutdown: 109 * 110 * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_DOWN 111 * FUNC: openvpn_plugin_client_destructor_v1 (top-level "generic" client) 112 * FUNC: openvpn_plugin_close_v1 113 */ 114#define OPENVPN_PLUGIN_UP 0 115#define OPENVPN_PLUGIN_DOWN 1 116#define OPENVPN_PLUGIN_ROUTE_UP 2 117#define OPENVPN_PLUGIN_IPCHANGE 3 118#define OPENVPN_PLUGIN_TLS_VERIFY 4 119#define OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY 5 120#define OPENVPN_PLUGIN_CLIENT_CONNECT 6 121#define OPENVPN_PLUGIN_CLIENT_DISCONNECT 7 122#define OPENVPN_PLUGIN_LEARN_ADDRESS 8 123#define OPENVPN_PLUGIN_CLIENT_CONNECT_V2 9 124#define OPENVPN_PLUGIN_TLS_FINAL 10 125#define OPENVPN_PLUGIN_ENABLE_PF 11 126#define OPENVPN_PLUGIN_ROUTE_PREDOWN 12 127#define OPENVPN_PLUGIN_N 13 128 129/* 130 * Build a mask out of a set of plug-in types. 131 */ 132#define OPENVPN_PLUGIN_MASK(x) (1<<(x)) 133 134/* 135 * A pointer to a plugin-defined object which contains 136 * the object state. 137 */ 138typedef void *openvpn_plugin_handle_t; 139 140/* 141 * Return value for openvpn_plugin_func_v1 function 142 */ 143#define OPENVPN_PLUGIN_FUNC_SUCCESS 0 144#define OPENVPN_PLUGIN_FUNC_ERROR 1 145#define OPENVPN_PLUGIN_FUNC_DEFERRED 2 146 147/* 148 * For Windows (needs to be modified for MSVC) 149 */ 150#if defined(WIN32) && !defined(OPENVPN_PLUGIN_H) 151# define OPENVPN_EXPORT __declspec(dllexport) 152#else 153# define OPENVPN_EXPORT 154#endif 155 156/* 157 * If OPENVPN_PLUGIN_H is defined, we know that we are being 158 * included in an OpenVPN compile, rather than a plugin compile. 159 */ 160#ifdef OPENVPN_PLUGIN_H 161 162/* 163 * We are compiling OpenVPN. 164 */ 165#define OPENVPN_PLUGIN_DEF typedef 166#define OPENVPN_PLUGIN_FUNC(name) (*name) 167 168#else 169 170/* 171 * We are compiling plugin. 172 */ 173#define OPENVPN_PLUGIN_DEF OPENVPN_EXPORT 174#define OPENVPN_PLUGIN_FUNC(name) name 175 176#endif 177 178/* 179 * Used by openvpn_plugin_func to return structured 180 * data. The plugin should allocate all structure 181 * instances, name strings, and value strings with 182 * malloc, since OpenVPN will assume that it 183 * can free the list by calling free() over the same. 184 */ 185struct openvpn_plugin_string_list 186{ 187 struct openvpn_plugin_string_list *next; 188 char *name; 189 char *value; 190}; 191 192 193/* openvpn_plugin_{open,func}_v3() related structs */ 194 195/* Defines version of the v3 plugin argument structs 196 * 197 * Whenever one or more of these structs are modified, this constant 198 * must be updated. A changelog should be appended in this comment 199 * as well, to make it easier to see what information is available 200 * in the different versions. 201 * 202 * Version Comment 203 * 1 Initial plugin v3 structures providing the same API as 204 * the v2 plugin interface + X509 certificate information. 205 * 206 */ 207#define OPENVPN_PLUGINv3_STRUCTVER 1 208 209/** 210 * Definitions needed for the plug-in callback functions. 211 */ 212typedef enum 213{ 214 PLOG_ERR = (1 << 0), /* Error condition message */ 215 PLOG_WARN = (1 << 1), /* General warning message */ 216 PLOG_NOTE = (1 << 2), /* Informational message */ 217 PLOG_DEBUG = (1 << 3), /* Debug message, displayed if verb >= 7 */ 218 219 PLOG_ERRNO = (1 << 8), /* Add error description to message */ 220 PLOG_NOMUTE = (1 << 9), /* Mute setting does not apply for message */ 221 222} openvpn_plugin_log_flags_t; 223 224 225#ifdef __GNUC__ 226#if __USE_MINGW_ANSI_STDIO 227# define _ovpn_chk_fmt(a, b) __attribute__ ((format(gnu_printf, (a), (b)))) 228#else 229# define _ovpn_chk_fmt(a, b) __attribute__ ((format(__printf__, (a), (b)))) 230#endif 231#else 232# define _ovpn_chk_fmt(a, b) 233#endif 234 235typedef void (*plugin_log_t) (openvpn_plugin_log_flags_t flags, 236 const char *plugin_name, 237 const char *format, ...) _ovpn_chk_fmt(3, 4); 238 239typedef void (*plugin_vlog_t) (openvpn_plugin_log_flags_t flags, 240 const char *plugin_name, 241 const char *format, 242 va_list arglist) _ovpn_chk_fmt(3, 0); 243 244#undef _ovpn_chk_fmt 245 246/** 247 * Used by the openvpn_plugin_open_v3() function to pass callback 248 * function pointers to the plug-in. 249 * 250 * plugin_log 251 * plugin_vlog : Use these functions to add information to the OpenVPN log file. 252 * Messages will only be displayed if the plugin_name parameter 253 * is set. PLOG_DEBUG messages will only be displayed with plug-in 254 * debug log verbosity (at the time of writing that's verb >= 7). 255 */ 256struct openvpn_plugin_callbacks 257{ 258 plugin_log_t plugin_log; 259 plugin_vlog_t plugin_vlog; 260}; 261 262/** 263 * Arguments used to transport variables to the plug-in. 264 * The struct openvpn_plugin_args_open_in is only used 265 * by the openvpn_plugin_open_v3() function. 266 * 267 * STRUCT MEMBERS 268 * 269 * type_mask : Set by OpenVPN to the logical OR of all script 270 * types which this version of OpenVPN supports. 271 * 272 * argv : a NULL-terminated array of options provided to the OpenVPN 273 * "plug-in" directive. argv[0] is the dynamic library pathname. 274 * 275 * envp : a NULL-terminated array of OpenVPN-set environmental 276 * variables in "name=value" format. Note that for security reasons, 277 * these variables are not actually written to the "official" 278 * environmental variable store of the process. 279 * 280 * callbacks : a pointer to the plug-in callback function struct. 281 * 282 */ 283struct openvpn_plugin_args_open_in 284{ 285 const int type_mask; 286 const char ** const argv; 287 const char ** const envp; 288 struct openvpn_plugin_callbacks *callbacks; 289}; 290 291 292/** 293 * Arguments used to transport variables from the plug-in back 294 * to the OpenVPN process. The struct openvpn_plugin_args_open_return 295 * is only used by the openvpn_plugin_open_v3() function. 296 * 297 * STRUCT MEMBERS 298 * 299 * *type_mask : The plug-in should set this value to the logical OR of all script 300 * types which the plug-in wants to intercept. For example, if the 301 * script wants to intercept the client-connect and client-disconnect 302 * script types: 303 * 304 * *type_mask = OPENVPN_PLUGIN_MASK(OPENVPN_PLUGIN_CLIENT_CONNECT) 305 * | OPENVPN_PLUGIN_MASK(OPENVPN_PLUGIN_CLIENT_DISCONNECT) 306 * 307 * *handle : Pointer to a global plug-in context, created by the plug-in. This pointer 308 * is passed on to the other plug-in calls. 309 * 310 * return_list : used to return data back to OpenVPN. 311 * 312 */ 313struct openvpn_plugin_args_open_return 314{ 315 int type_mask; 316 openvpn_plugin_handle_t *handle; 317 struct openvpn_plugin_string_list **return_list; 318}; 319 320/** 321 * Arguments used to transport variables to and from the 322 * plug-in. The struct openvpn_plugin_args_func is only used 323 * by the openvpn_plugin_func_v3() function. 324 * 325 * STRUCT MEMBERS: 326 * 327 * type : one of the PLUGIN_x types. 328 * 329 * argv : a NULL-terminated array of "command line" options which 330 * would normally be passed to the script. argv[0] is the dynamic 331 * library pathname. 332 * 333 * envp : a NULL-terminated array of OpenVPN-set environmental 334 * variables in "name=value" format. Note that for security reasons, 335 * these variables are not actually written to the "official" 336 * environmental variable store of the process. 337 * 338 * *handle : Pointer to a global plug-in context, created by the plug-in's openvpn_plugin_open_v3(). 339 * 340 * *per_client_context : the per-client context pointer which was returned by 341 * openvpn_plugin_client_constructor_v1, if defined. 342 * 343 * current_cert_depth : Certificate depth of the certificate being passed over (only if compiled with ENABLE_SSL defined) 344 * 345 * *current_cert : X509 Certificate object received from the client (only if compiled with ENABLE_SSL defined) 346 * 347 */ 348struct openvpn_plugin_args_func_in 349{ 350 const int type; 351 const char ** const argv; 352 const char ** const envp; 353 openvpn_plugin_handle_t handle; 354 void *per_client_context; 355#ifdef ENABLE_SSL 356 int current_cert_depth; 357 openvpn_x509_cert_t *current_cert; 358#else 359 int __current_cert_depth_disabled; /* Unused, for compatibility purposes only */ 360 void *__current_cert_disabled; /* Unused, for compatibility purposes only */ 361#endif 362}; 363 364 365/** 366 * Arguments used to transport variables to and from the 367 * plug-in. The struct openvpn_plugin_args_func is only used 368 * by the openvpn_plugin_func_v3() function. 369 * 370 * STRUCT MEMBERS: 371 * 372 * return_list : used to return data back to OpenVPN for further processing/usage by 373 * the OpenVPN executable. 374 * 375 */ 376struct openvpn_plugin_args_func_return 377{ 378 struct openvpn_plugin_string_list **return_list; 379}; 380 381/* 382 * Multiple plugin modules can be cascaded, and modules can be 383 * used in tandem with scripts. The order of operation is that 384 * the module func() functions are called in the order that 385 * the modules were specified in the config file. If a script 386 * was specified as well, it will be called last. If the 387 * return code of the module/script controls an authentication 388 * function (such as tls-verify or auth-user-pass-verify), then 389 * every module and script must return success (0) in order for 390 * the connection to be authenticated. 391 * 392 * Notes: 393 * 394 * Plugins which use a privilege-separation model (by forking in 395 * their initialization function before the main OpenVPN process 396 * downgrades root privileges and/or executes a chroot) must 397 * daemonize after a fork if the "daemon" environmental variable is 398 * set. In addition, if the "daemon_log_redirect" variable is set, 399 * the plugin should preserve stdout/stderr across the daemon() 400 * syscall. See the daemonize() function in plugin/auth-pam/auth-pam.c 401 * for an example. 402 */ 403 404/* 405 * Prototypes for functions which OpenVPN plug-ins must define. 406 */ 407 408/* 409 * FUNCTION: openvpn_plugin_open_v2 410 * 411 * REQUIRED: YES 412 * 413 * Called on initial plug-in load. OpenVPN will preserve plug-in state 414 * across SIGUSR1 restarts but not across SIGHUP restarts. A SIGHUP reset 415 * will cause the plugin to be closed and reopened. 416 * 417 * ARGUMENTS 418 * 419 * *type_mask : Set by OpenVPN to the logical OR of all script 420 * types which this version of OpenVPN supports. The plug-in 421 * should set this value to the logical OR of all script types 422 * which the plug-in wants to intercept. For example, if the 423 * script wants to intercept the client-connect and 424 * client-disconnect script types: 425 * 426 * *type_mask = OPENVPN_PLUGIN_MASK(OPENVPN_PLUGIN_CLIENT_CONNECT) 427 * | OPENVPN_PLUGIN_MASK(OPENVPN_PLUGIN_CLIENT_DISCONNECT) 428 * 429 * argv : a NULL-terminated array of options provided to the OpenVPN 430 * "plug-in" directive. argv[0] is the dynamic library pathname. 431 * 432 * envp : a NULL-terminated array of OpenVPN-set environmental 433 * variables in "name=value" format. Note that for security reasons, 434 * these variables are not actually written to the "official" 435 * environmental variable store of the process. 436 * 437 * return_list : used to return data back to OpenVPN. 438 * 439 * RETURN VALUE 440 * 441 * An openvpn_plugin_handle_t value on success, NULL on failure 442 */ 443OPENVPN_PLUGIN_DEF openvpn_plugin_handle_t OPENVPN_PLUGIN_FUNC(openvpn_plugin_open_v2) 444 (unsigned int *type_mask, 445 const char *argv[], 446 const char *envp[], 447 struct openvpn_plugin_string_list **return_list); 448 449/* 450 * FUNCTION: openvpn_plugin_func_v2 451 * 452 * Called to perform the work of a given script type. 453 * 454 * REQUIRED: YES 455 * 456 * ARGUMENTS 457 * 458 * handle : the openvpn_plugin_handle_t value which was returned by 459 * openvpn_plugin_open. 460 * 461 * type : one of the PLUGIN_x types 462 * 463 * argv : a NULL-terminated array of "command line" options which 464 * would normally be passed to the script. argv[0] is the dynamic 465 * library pathname. 466 * 467 * envp : a NULL-terminated array of OpenVPN-set environmental 468 * variables in "name=value" format. Note that for security reasons, 469 * these variables are not actually written to the "official" 470 * environmental variable store of the process. 471 * 472 * per_client_context : the per-client context pointer which was returned by 473 * openvpn_plugin_client_constructor_v1, if defined. 474 * 475 * return_list : used to return data back to OpenVPN. 476 * 477 * RETURN VALUE 478 * 479 * OPENVPN_PLUGIN_FUNC_SUCCESS on success, OPENVPN_PLUGIN_FUNC_ERROR on failure 480 * 481 * In addition, OPENVPN_PLUGIN_FUNC_DEFERRED may be returned by 482 * OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY. This enables asynchronous 483 * authentication where the plugin (or one of its agents) may indicate 484 * authentication success/failure some number of seconds after the return 485 * of the OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY handler by writing a single 486 * char to the file named by auth_control_file in the environmental variable 487 * list (envp). 488 * 489 * first char of auth_control_file: 490 * '0' -- indicates auth failure 491 * '1' -- indicates auth success 492 * 493 * OpenVPN will delete the auth_control_file after it goes out of scope. 494 * 495 * If an OPENVPN_PLUGIN_ENABLE_PF handler is defined and returns success 496 * for a particular client instance, packet filtering will be enabled for that 497 * instance. OpenVPN will then attempt to read the packet filter configuration 498 * from the temporary file named by the environmental variable pf_file. This 499 * file may be generated asynchronously and may be dynamically updated during the 500 * client session, however the client will be blocked from sending or receiving 501 * VPN tunnel packets until the packet filter file has been generated. OpenVPN 502 * will periodically test the packet filter file over the life of the client 503 * instance and reload when modified. OpenVPN will delete the packet filter file 504 * when the client instance goes out of scope. 505 * 506 * Packet filter file grammar: 507 * 508 * [CLIENTS DROP|ACCEPT] 509 * {+|-}common_name1 510 * {+|-}common_name2 511 * . . . 512 * [SUBNETS DROP|ACCEPT] 513 * {+|-}subnet1 514 * {+|-}subnet2 515 * . . . 516 * [END] 517 * 518 * Subnet: IP-ADDRESS | IP-ADDRESS/NUM_NETWORK_BITS 519 * 520 * CLIENTS refers to the set of clients (by their common-name) which 521 * this instance is allowed ('+') to connect to, or is excluded ('-') 522 * from connecting to. Note that in the case of client-to-client 523 * connections, such communication must be allowed by the packet filter 524 * configuration files of both clients. 525 * 526 * SUBNETS refers to IP addresses or IP address subnets which this 527 * instance may connect to ('+') or is excluded ('-') from connecting 528 * to. 529 * 530 * DROP or ACCEPT defines default policy when there is no explicit match 531 * for a common-name or subnet. The [END] tag must exist. A special 532 * purpose tag called [KILL] will immediately kill the client instance. 533 * A given client or subnet rule applies to both incoming and outgoing 534 * packets. 535 * 536 * See plugin/defer/simple.c for an example on using asynchronous 537 * authentication and client-specific packet filtering. 538 */ 539OPENVPN_PLUGIN_DEF int OPENVPN_PLUGIN_FUNC(openvpn_plugin_func_v2) 540 (openvpn_plugin_handle_t handle, 541 const int type, 542 const char *argv[], 543 const char *envp[], 544 void *per_client_context, 545 struct openvpn_plugin_string_list **return_list); 546 547 548/* 549 * FUNCTION: openvpn_plugin_open_v3 550 * 551 * REQUIRED: YES 552 * 553 * Called on initial plug-in load. OpenVPN will preserve plug-in state 554 * across SIGUSR1 restarts but not across SIGHUP restarts. A SIGHUP reset 555 * will cause the plugin to be closed and reopened. 556 * 557 * ARGUMENTS 558 * 559 * version : fixed value, defines the API version of the OpenVPN plug-in API. The plug-in 560 * should validate that this value is matching the OPENVPN_PLUGIN_VERSION value. 561 * 562 * arguments : Structure with all arguments available to the plug-in. 563 * 564 * retptr : used to return data back to OpenVPN. 565 * 566 * RETURN VALUE 567 * 568 * OPENVPN_PLUGIN_FUNC_SUCCESS on success, OPENVPN_PLUGIN_FUNC_ERROR on failure 569 */ 570OPENVPN_PLUGIN_DEF int OPENVPN_PLUGIN_FUNC(openvpn_plugin_open_v3) 571 (const int version, 572 struct openvpn_plugin_args_open_in const *arguments, 573 struct openvpn_plugin_args_open_return *retptr); 574 575/* 576 * FUNCTION: openvpn_plugin_func_v3 577 * 578 * Called to perform the work of a given script type. 579 * 580 * REQUIRED: YES 581 * 582 * ARGUMENTS 583 * 584 * version : fixed value, defines the API version of the OpenVPN plug-in API. The plug-in 585 * should validate that this value is matching the OPENVPN_PLUGIN_VERSION value. 586 * 587 * handle : the openvpn_plugin_handle_t value which was returned by 588 * openvpn_plugin_open. 589 * 590 * return_list : used to return data back to OpenVPN. 591 * 592 * RETURN VALUE 593 * 594 * OPENVPN_PLUGIN_FUNC_SUCCESS on success, OPENVPN_PLUGIN_FUNC_ERROR on failure 595 * 596 * In addition, OPENVPN_PLUGIN_FUNC_DEFERRED may be returned by 597 * OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY. This enables asynchronous 598 * authentication where the plugin (or one of its agents) may indicate 599 * authentication success/failure some number of seconds after the return 600 * of the OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY handler by writing a single 601 * char to the file named by auth_control_file in the environmental variable 602 * list (envp). 603 * 604 * first char of auth_control_file: 605 * '0' -- indicates auth failure 606 * '1' -- indicates auth success 607 * 608 * OpenVPN will delete the auth_control_file after it goes out of scope. 609 * 610 * If an OPENVPN_PLUGIN_ENABLE_PF handler is defined and returns success 611 * for a particular client instance, packet filtering will be enabled for that 612 * instance. OpenVPN will then attempt to read the packet filter configuration 613 * from the temporary file named by the environmental variable pf_file. This 614 * file may be generated asynchronously and may be dynamically updated during the 615 * client session, however the client will be blocked from sending or receiving 616 * VPN tunnel packets until the packet filter file has been generated. OpenVPN 617 * will periodically test the packet filter file over the life of the client 618 * instance and reload when modified. OpenVPN will delete the packet filter file 619 * when the client instance goes out of scope. 620 * 621 * Packet filter file grammar: 622 * 623 * [CLIENTS DROP|ACCEPT] 624 * {+|-}common_name1 625 * {+|-}common_name2 626 * . . . 627 * [SUBNETS DROP|ACCEPT] 628 * {+|-}subnet1 629 * {+|-}subnet2 630 * . . . 631 * [END] 632 * 633 * Subnet: IP-ADDRESS | IP-ADDRESS/NUM_NETWORK_BITS 634 * 635 * CLIENTS refers to the set of clients (by their common-name) which 636 * this instance is allowed ('+') to connect to, or is excluded ('-') 637 * from connecting to. Note that in the case of client-to-client 638 * connections, such communication must be allowed by the packet filter 639 * configuration files of both clients. 640 * 641 * SUBNETS refers to IP addresses or IP address subnets which this 642 * instance may connect to ('+') or is excluded ('-') from connecting 643 * to. 644 * 645 * DROP or ACCEPT defines default policy when there is no explicit match 646 * for a common-name or subnet. The [END] tag must exist. A special 647 * purpose tag called [KILL] will immediately kill the client instance. 648 * A given client or subnet rule applies to both incoming and outgoing 649 * packets. 650 * 651 * See plugin/defer/simple.c for an example on using asynchronous 652 * authentication and client-specific packet filtering. 653 */ 654OPENVPN_PLUGIN_DEF int OPENVPN_PLUGIN_FUNC(openvpn_plugin_func_v3) 655 (const int version, 656 struct openvpn_plugin_args_func_in const *arguments, 657 struct openvpn_plugin_args_func_return *retptr); 658 659/* 660 * FUNCTION: openvpn_plugin_close_v1 661 * 662 * REQUIRED: YES 663 * 664 * ARGUMENTS 665 * 666 * handle : the openvpn_plugin_handle_t value which was returned by 667 * openvpn_plugin_open. 668 * 669 * Called immediately prior to plug-in unload. 670 */ 671OPENVPN_PLUGIN_DEF void OPENVPN_PLUGIN_FUNC(openvpn_plugin_close_v1) 672 (openvpn_plugin_handle_t handle); 673 674/* 675 * FUNCTION: openvpn_plugin_abort_v1 676 * 677 * REQUIRED: NO 678 * 679 * ARGUMENTS 680 * 681 * handle : the openvpn_plugin_handle_t value which was returned by 682 * openvpn_plugin_open. 683 * 684 * Called when OpenVPN is in the process of aborting due to a fatal error. 685 * Will only be called on an open context returned by a prior successful 686 * openvpn_plugin_open callback. 687 */ 688OPENVPN_PLUGIN_DEF void OPENVPN_PLUGIN_FUNC(openvpn_plugin_abort_v1) 689 (openvpn_plugin_handle_t handle); 690 691/* 692 * FUNCTION: openvpn_plugin_client_constructor_v1 693 * 694 * Called to allocate a per-client memory region, which 695 * is then passed to the openvpn_plugin_func_v2 function. 696 * This function is called every time the OpenVPN server 697 * constructs a client instance object, which normally 698 * occurs when a session-initiating packet is received 699 * by a new client, even before the client has authenticated. 700 * 701 * This function should allocate the private memory needed 702 * by the plugin to track individual OpenVPN clients, and 703 * return a void * to this memory region. 704 * 705 * REQUIRED: NO 706 * 707 * ARGUMENTS 708 * 709 * handle : the openvpn_plugin_handle_t value which was returned by 710 * openvpn_plugin_open. 711 * 712 * RETURN VALUE 713 * 714 * void * pointer to plugin's private per-client memory region, or NULL 715 * if no memory region is required. 716 */ 717OPENVPN_PLUGIN_DEF void * OPENVPN_PLUGIN_FUNC(openvpn_plugin_client_constructor_v1) 718 (openvpn_plugin_handle_t handle); 719 720/* 721 * FUNCTION: openvpn_plugin_client_destructor_v1 722 * 723 * This function is called on client instance object destruction. 724 * 725 * REQUIRED: NO 726 * 727 * ARGUMENTS 728 * 729 * handle : the openvpn_plugin_handle_t value which was returned by 730 * openvpn_plugin_open. 731 * 732 * per_client_context : the per-client context pointer which was returned by 733 * openvpn_plugin_client_constructor_v1, if defined. 734 */ 735OPENVPN_PLUGIN_DEF void OPENVPN_PLUGIN_FUNC(openvpn_plugin_client_destructor_v1) 736 (openvpn_plugin_handle_t handle, void *per_client_context); 737 738/* 739 * FUNCTION: openvpn_plugin_select_initialization_point_v1 740 * 741 * Several different points exist in OpenVPN's initialization sequence where 742 * the openvpn_plugin_open function can be called. While the default is 743 * OPENVPN_PLUGIN_INIT_PRE_DAEMON, this function can be used to select a 744 * different initialization point. For example, if your plugin needs to 745 * return configuration parameters to OpenVPN, use 746 * OPENVPN_PLUGIN_INIT_PRE_CONFIG_PARSE. 747 * 748 * REQUIRED: NO 749 * 750 * RETURN VALUE: 751 * 752 * An OPENVPN_PLUGIN_INIT_x value. 753 */ 754#define OPENVPN_PLUGIN_INIT_PRE_CONFIG_PARSE 1 755#define OPENVPN_PLUGIN_INIT_PRE_DAEMON 2 /* default */ 756#define OPENVPN_PLUGIN_INIT_POST_DAEMON 3 757#define OPENVPN_PLUGIN_INIT_POST_UID_CHANGE 4 758 759OPENVPN_PLUGIN_DEF int OPENVPN_PLUGIN_FUNC(openvpn_plugin_select_initialization_point_v1) 760 (void); 761 762/* 763 * FUNCTION: openvpn_plugin_min_version_required_v1 764 * 765 * This function is called by OpenVPN to query the minimum 766 plugin interface version number required by the plugin. 767 * 768 * REQUIRED: NO 769 * 770 * RETURN VALUE 771 * 772 * The minimum OpenVPN plugin interface version number necessary to support 773 * this plugin. 774 */ 775OPENVPN_PLUGIN_DEF int OPENVPN_PLUGIN_FUNC(openvpn_plugin_min_version_required_v1) 776 (void); 777 778/* 779 * Deprecated functions which are still supported for backward compatibility. 780 */ 781 782OPENVPN_PLUGIN_DEF openvpn_plugin_handle_t OPENVPN_PLUGIN_FUNC(openvpn_plugin_open_v1) 783 (unsigned int *type_mask, 784 const char *argv[], 785 const char *envp[]); 786 787OPENVPN_PLUGIN_DEF int OPENVPN_PLUGIN_FUNC(openvpn_plugin_func_v1) 788 (openvpn_plugin_handle_t handle, const int type, const char *argv[], const char *envp[]); 789 790#ifdef __cplusplus 791} 792#endif 793 794#endif /* OPENVPN_PLUGIN_H_ */ 795