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