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