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