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-2022 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 * In addition the OPENVPN_PLUGIN_CLIENT_CONNECT_DEFER and 571 * OPENVPN_PLUGIN_CLIENT_CONNECT_DEFER_V2 are called when OpenVPN tries to 572 * get the deferred result. For a V2 call implementing this function is 573 * required as information is not passed by files. For the normal version 574 * the call is optional. 575 * 576 * first char of auth_control_file: 577 * '0' -- indicates auth failure 578 * '1' -- indicates auth success 579 * 580 * OpenVPN will delete the auth_control_file after it goes out of scope. 581 * 582 * If an OPENVPN_PLUGIN_ENABLE_PF handler is defined and returns success 583 * for a particular client instance, packet filtering will be enabled for that 584 * instance. OpenVPN will then attempt to read the packet filter configuration 585 * from the temporary file named by the environmental variable pf_file. This 586 * file may be generated asynchronously and may be dynamically updated during the 587 * client session, however the client will be blocked from sending or receiving 588 * VPN tunnel packets until the packet filter file has been generated. OpenVPN 589 * will periodically test the packet filter file over the life of the client 590 * instance and reload when modified. OpenVPN will delete the packet filter file 591 * when the client instance goes out of scope. 592 * 593 * Packet filter file grammar: 594 * 595 * [CLIENTS DROP|ACCEPT] 596 * {+|-}common_name1 597 * {+|-}common_name2 598 * . . . 599 * [SUBNETS DROP|ACCEPT] 600 * {+|-}subnet1 601 * {+|-}subnet2 602 * . . . 603 * [END] 604 * 605 * Subnet: IP-ADDRESS | IP-ADDRESS/NUM_NETWORK_BITS 606 * 607 * CLIENTS refers to the set of clients (by their common-name) which 608 * this instance is allowed ('+') to connect to, or is excluded ('-') 609 * from connecting to. Note that in the case of client-to-client 610 * connections, such communication must be allowed by the packet filter 611 * configuration files of both clients. 612 * 613 * SUBNETS refers to IP addresses or IP address subnets which this 614 * instance may connect to ('+') or is excluded ('-') from connecting 615 * to. 616 * 617 * DROP or ACCEPT defines default policy when there is no explicit match 618 * for a common-name or subnet. The [END] tag must exist. A special 619 * purpose tag called [KILL] will immediately kill the client instance. 620 * A given client or subnet rule applies to both incoming and outgoing 621 * packets. 622 * 623 * See plugin/defer/simple.c for an example on using asynchronous 624 * authentication and client-specific packet filtering. 625 */ 626OPENVPN_PLUGIN_DEF int OPENVPN_PLUGIN_FUNC(openvpn_plugin_func_v2) 627 (openvpn_plugin_handle_t handle, 628 const int type, 629 const char *argv[], 630 const char *envp[], 631 void *per_client_context, 632 struct openvpn_plugin_string_list **return_list); 633 634 635/* 636 * FUNCTION: openvpn_plugin_open_v3 637 * 638 * REQUIRED: YES 639 * 640 * Called on initial plug-in load. OpenVPN will preserve plug-in state 641 * across SIGUSR1 restarts but not across SIGHUP restarts. A SIGHUP reset 642 * will cause the plugin to be closed and reopened. 643 * 644 * ARGUMENTS 645 * 646 * version : fixed value, defines the API version of the OpenVPN plug-in API. The plug-in 647 * should validate that this value is matching the OPENVPN_PLUGINv3_STRUCTVER 648 * value. 649 * 650 * arguments : Structure with all arguments available to the plug-in. 651 * 652 * retptr : used to return data back to OpenVPN. 653 * 654 * RETURN VALUE 655 * 656 * OPENVPN_PLUGIN_FUNC_SUCCESS on success, OPENVPN_PLUGIN_FUNC_ERROR on failure 657 */ 658OPENVPN_PLUGIN_DEF int OPENVPN_PLUGIN_FUNC(openvpn_plugin_open_v3) 659 (const int version, 660 struct openvpn_plugin_args_open_in const *arguments, 661 struct openvpn_plugin_args_open_return *retptr); 662 663/* 664 * FUNCTION: openvpn_plugin_func_v3 665 * 666 * Called to perform the work of a given script type. 667 * 668 * REQUIRED: YES 669 * 670 * ARGUMENTS 671 * 672 * version : fixed value, defines the API version of the OpenVPN plug-in API. The plug-in 673 * should validate that this value is matching the OPENVPN_PLUGINv3_STRUCTVER 674 * value. 675 * 676 * arguments : Structure with all arguments available to the plug-in. 677 * 678 * retptr : used to return data back to OpenVPN. 679 * 680 * RETURN VALUE 681 * 682 * OPENVPN_PLUGIN_FUNC_SUCCESS on success, OPENVPN_PLUGIN_FUNC_ERROR on failure 683 * 684 * In addition, OPENVPN_PLUGIN_FUNC_DEFERRED may be returned by 685 * OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY. This enables asynchronous 686 * authentication where the plugin (or one of its agents) may indicate 687 * authentication success/failure some number of seconds after the return 688 * of the OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY handler by writing a single 689 * char to the file named by auth_control_file in the environmental variable 690 * list (envp). 691 * 692 * first char of auth_control_file: 693 * '0' -- indicates auth failure 694 * '1' -- indicates auth success 695 * 696 * OpenVPN will delete the auth_control_file after it goes out of scope. 697 * 698 * If an OPENVPN_PLUGIN_ENABLE_PF handler is defined and returns success 699 * for a particular client instance, packet filtering will be enabled for that 700 * instance. OpenVPN will then attempt to read the packet filter configuration 701 * from the temporary file named by the environmental variable pf_file. This 702 * file may be generated asynchronously and may be dynamically updated during the 703 * client session, however the client will be blocked from sending or receiving 704 * VPN tunnel packets until the packet filter file has been generated. OpenVPN 705 * will periodically test the packet filter file over the life of the client 706 * instance and reload when modified. OpenVPN will delete the packet filter file 707 * when the client instance goes out of scope. 708 * 709 * Packet filter file grammar: 710 * 711 * [CLIENTS DROP|ACCEPT] 712 * {+|-}common_name1 713 * {+|-}common_name2 714 * . . . 715 * [SUBNETS DROP|ACCEPT] 716 * {+|-}subnet1 717 * {+|-}subnet2 718 * . . . 719 * [END] 720 * 721 * Subnet: IP-ADDRESS | IP-ADDRESS/NUM_NETWORK_BITS 722 * 723 * CLIENTS refers to the set of clients (by their common-name) which 724 * this instance is allowed ('+') to connect to, or is excluded ('-') 725 * from connecting to. Note that in the case of client-to-client 726 * connections, such communication must be allowed by the packet filter 727 * configuration files of both clients. 728 * 729 * SUBNETS refers to IP addresses or IP address subnets which this 730 * instance may connect to ('+') or is excluded ('-') from connecting 731 * to. 732 * 733 * DROP or ACCEPT defines default policy when there is no explicit match 734 * for a common-name or subnet. The [END] tag must exist. A special 735 * purpose tag called [KILL] will immediately kill the client instance. 736 * A given client or subnet rule applies to both incoming and outgoing 737 * packets. 738 * 739 * See sample/sample-plugins/defer/simple.c for an example on using 740 * asynchronous authentication and client-specific packet filtering. 741 */ 742OPENVPN_PLUGIN_DEF int OPENVPN_PLUGIN_FUNC(openvpn_plugin_func_v3) 743 (const int version, 744 struct openvpn_plugin_args_func_in const *arguments, 745 struct openvpn_plugin_args_func_return *retptr); 746 747/* 748 * FUNCTION: openvpn_plugin_close_v1 749 * 750 * REQUIRED: YES 751 * 752 * ARGUMENTS 753 * 754 * handle : the openvpn_plugin_handle_t value which was returned by 755 * openvpn_plugin_open. 756 * 757 * Called immediately prior to plug-in unload. 758 */ 759OPENVPN_PLUGIN_DEF void OPENVPN_PLUGIN_FUNC(openvpn_plugin_close_v1) 760 (openvpn_plugin_handle_t handle); 761 762/* 763 * FUNCTION: openvpn_plugin_abort_v1 764 * 765 * REQUIRED: NO 766 * 767 * ARGUMENTS 768 * 769 * handle : the openvpn_plugin_handle_t value which was returned by 770 * openvpn_plugin_open. 771 * 772 * Called when OpenVPN is in the process of aborting due to a fatal error. 773 * Will only be called on an open context returned by a prior successful 774 * openvpn_plugin_open callback. 775 */ 776OPENVPN_PLUGIN_DEF void OPENVPN_PLUGIN_FUNC(openvpn_plugin_abort_v1) 777 (openvpn_plugin_handle_t handle); 778 779/* 780 * FUNCTION: openvpn_plugin_client_constructor_v1 781 * 782 * Called to allocate a per-client memory region, which 783 * is then passed to the openvpn_plugin_func_v2 function. 784 * This function is called every time the OpenVPN server 785 * constructs a client instance object, which normally 786 * occurs when a session-initiating packet is received 787 * by a new client, even before the client has authenticated. 788 * 789 * This function should allocate the private memory needed 790 * by the plugin to track individual OpenVPN clients, and 791 * return a void * to this memory region. 792 * 793 * REQUIRED: NO 794 * 795 * ARGUMENTS 796 * 797 * handle : the openvpn_plugin_handle_t value which was returned by 798 * openvpn_plugin_open. 799 * 800 * RETURN VALUE 801 * 802 * void * pointer to plugin's private per-client memory region, or NULL 803 * if no memory region is required. 804 */ 805OPENVPN_PLUGIN_DEF void *OPENVPN_PLUGIN_FUNC(openvpn_plugin_client_constructor_v1) 806 (openvpn_plugin_handle_t handle); 807 808/* 809 * FUNCTION: openvpn_plugin_client_destructor_v1 810 * 811 * This function is called on client instance object destruction. 812 * 813 * REQUIRED: NO 814 * 815 * ARGUMENTS 816 * 817 * handle : the openvpn_plugin_handle_t value which was returned by 818 * openvpn_plugin_open. 819 * 820 * per_client_context : the per-client context pointer which was returned by 821 * openvpn_plugin_client_constructor_v1, if defined. 822 */ 823OPENVPN_PLUGIN_DEF void OPENVPN_PLUGIN_FUNC(openvpn_plugin_client_destructor_v1) 824 (openvpn_plugin_handle_t handle, void *per_client_context); 825 826/* 827 * FUNCTION: openvpn_plugin_select_initialization_point_v1 828 * 829 * Several different points exist in OpenVPN's initialization sequence where 830 * the openvpn_plugin_open function can be called. While the default is 831 * OPENVPN_PLUGIN_INIT_PRE_DAEMON, this function can be used to select a 832 * different initialization point. For example, if your plugin needs to 833 * return configuration parameters to OpenVPN, use 834 * OPENVPN_PLUGIN_INIT_PRE_CONFIG_PARSE. 835 * 836 * REQUIRED: NO 837 * 838 * RETURN VALUE: 839 * 840 * An OPENVPN_PLUGIN_INIT_x value. 841 */ 842#define OPENVPN_PLUGIN_INIT_PRE_CONFIG_PARSE 1 843#define OPENVPN_PLUGIN_INIT_PRE_DAEMON 2 /* default */ 844#define OPENVPN_PLUGIN_INIT_POST_DAEMON 3 845#define OPENVPN_PLUGIN_INIT_POST_UID_CHANGE 4 846 847OPENVPN_PLUGIN_DEF int OPENVPN_PLUGIN_FUNC(openvpn_plugin_select_initialization_point_v1) 848 (void); 849 850/* 851 * FUNCTION: openvpn_plugin_min_version_required_v1 852 * 853 * This function is called by OpenVPN to query the minimum 854 * plugin interface version number required by the plugin. 855 * 856 * REQUIRED: NO 857 * 858 * RETURN VALUE 859 * 860 * The minimum OpenVPN plugin interface version number necessary to support 861 * this plugin. 862 */ 863OPENVPN_PLUGIN_DEF int OPENVPN_PLUGIN_FUNC(openvpn_plugin_min_version_required_v1) 864 (void); 865 866/* 867 * Deprecated functions which are still supported for backward compatibility. 868 */ 869 870OPENVPN_PLUGIN_DEF openvpn_plugin_handle_t OPENVPN_PLUGIN_FUNC(openvpn_plugin_open_v1) 871 (unsigned int *type_mask, 872 const char *argv[], 873 const char *envp[]); 874 875OPENVPN_PLUGIN_DEF int OPENVPN_PLUGIN_FUNC(openvpn_plugin_func_v1) 876 (openvpn_plugin_handle_t handle, const int type, const char *argv[], const char *envp[]); 877 878#ifdef __cplusplus 879} 880#endif 881 882#endif /* OPENVPN_PLUGIN_H_ */ 883