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