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-2010 OpenVPN Technologies, 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 20 * along with this program (see the file COPYING included with this 21 * distribution); if not, write to the Free Software Foundation, Inc., 22 * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 23 */ 24 25 #define OPENVPN_PLUGIN_VERSION 2 26 27 /* 28 * Plug-in types. These types correspond to the set of script callbacks 29 * supported by OpenVPN. 30 * 31 * This is the general call sequence to expect when running in server mode: 32 * 33 * Initial Server Startup: 34 * 35 * FUNC: openvpn_plugin_open_v1 36 * FUNC: openvpn_plugin_client_constructor_v1 (this is the top-level "generic" 37 * client template) 38 * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_UP 39 * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_ROUTE_UP 40 * 41 * New Client Connection: 42 * 43 * FUNC: openvpn_plugin_client_constructor_v1 44 * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_ENABLE_PF 45 * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_TLS_VERIFY (called once for every cert 46 * in the server chain) 47 * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY 48 * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_TLS_FINAL 49 * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_IPCHANGE 50 * 51 * [If OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY returned OPENVPN_PLUGIN_FUNC_DEFERRED, 52 * we don't proceed until authentication is verified via auth_control_file] 53 * 54 * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_CLIENT_CONNECT_V2 55 * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_LEARN_ADDRESS 56 * 57 * [Client session ensues] 58 * 59 * For each "TLS soft reset", according to reneg-sec option (or similar): 60 * 61 * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_ENABLE_PF 62 * 63 * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_TLS_VERIFY (called once for every cert 64 * in the server chain) 65 * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY 66 * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_TLS_FINAL 67 * 68 * [If OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY returned OPENVPN_PLUGIN_FUNC_DEFERRED, 69 * we expect that authentication is verified via auth_control_file within 70 * the number of seconds defined by the "hand-window" option. Data channel traffic 71 * will continue to flow uninterrupted during this period.] 72 * 73 * [Client session continues] 74 * 75 * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_CLIENT_DISCONNECT 76 * FUNC: openvpn_plugin_client_destructor_v1 77 * 78 * [ some time may pass ] 79 * 80 * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_LEARN_ADDRESS (this coincides with a 81 * lazy free of initial 82 * learned addr object) 83 * Server Shutdown: 84 * 85 * FUNC: openvpn_plugin_func_v1 OPENVPN_PLUGIN_DOWN 86 * FUNC: openvpn_plugin_client_destructor_v1 (top-level "generic" client) 87 * FUNC: openvpn_plugin_close_v1 88 */ 89 #define OPENVPN_PLUGIN_UP 0 90 #define OPENVPN_PLUGIN_DOWN 1 91 #define OPENVPN_PLUGIN_ROUTE_UP 2 92 #define OPENVPN_PLUGIN_IPCHANGE 3 93 #define OPENVPN_PLUGIN_TLS_VERIFY 4 94 #define OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY 5 95 #define OPENVPN_PLUGIN_CLIENT_CONNECT 6 96 #define OPENVPN_PLUGIN_CLIENT_DISCONNECT 7 97 #define OPENVPN_PLUGIN_LEARN_ADDRESS 8 98 #define OPENVPN_PLUGIN_CLIENT_CONNECT_V2 9 99 #define OPENVPN_PLUGIN_TLS_FINAL 10 100 #define OPENVPN_PLUGIN_ENABLE_PF 11 101 #define OPENVPN_PLUGIN_N 12 102 103 /* 104 * Build a mask out of a set of plug-in types. 105 */ 106 #define OPENVPN_PLUGIN_MASK(x) (1<<(x)) 107 108 /* 109 * A pointer to a plugin-defined object which contains 110 * the object state. 111 */ 112 typedef void *openvpn_plugin_handle_t; 113 114 /* 115 * Return value for openvpn_plugin_func_v1 function 116 */ 117 #define OPENVPN_PLUGIN_FUNC_SUCCESS 0 118 #define OPENVPN_PLUGIN_FUNC_ERROR 1 119 #define OPENVPN_PLUGIN_FUNC_DEFERRED 2 120 121 /* 122 * For Windows (needs to be modified for MSVC) 123 */ 124 #if defined(__MINGW32_VERSION) && !defined(OPENVPN_PLUGIN_H) 125 # define OPENVPN_EXPORT __declspec(dllexport) 126 #else 127 # define OPENVPN_EXPORT 128 #endif 129 130 /* 131 * If OPENVPN_PLUGIN_H is defined, we know that we are being 132 * included in an OpenVPN compile, rather than a plugin compile. 133 */ 134 #ifdef OPENVPN_PLUGIN_H 135 136 /* 137 * We are compiling OpenVPN. 138 */ 139 #define OPENVPN_PLUGIN_DEF typedef 140 #define OPENVPN_PLUGIN_FUNC(name) (*name) 141 142 #else 143 144 /* 145 * We are compiling plugin. 146 */ 147 #define OPENVPN_PLUGIN_DEF OPENVPN_EXPORT 148 #define OPENVPN_PLUGIN_FUNC(name) name 149 150 #endif 151 152 /* 153 * Used by openvpn_plugin_func to return structured 154 * data. The plugin should allocate all structure 155 * instances, name strings, and value strings with 156 * malloc, since OpenVPN will assume that it 157 * can free the list by calling free() over the same. 158 */ 159 struct openvpn_plugin_string_list 160 { 161 struct openvpn_plugin_string_list *next; 162 char *name; 163 char *value; 164 }; 165 166 /* 167 * Multiple plugin modules can be cascaded, and modules can be 168 * used in tandem with scripts. The order of operation is that 169 * the module func() functions are called in the order that 170 * the modules were specified in the config file. If a script 171 * was specified as well, it will be called last. If the 172 * return code of the module/script controls an authentication 173 * function (such as tls-verify or auth-user-pass-verify), then 174 * every module and script must return success (0) in order for 175 * the connection to be authenticated. 176 * 177 * Notes: 178 * 179 * Plugins which use a privilege-separation model (by forking in 180 * their initialization function before the main OpenVPN process 181 * downgrades root privileges and/or executes a chroot) must 182 * daemonize after a fork if the "daemon" environmental variable is 183 * set. In addition, if the "daemon_log_redirect" variable is set, 184 * the plugin should preserve stdout/stderr across the daemon() 185 * syscall. See the daemonize() function in plugin/auth-pam/auth-pam.c 186 * for an example. 187 */ 188 189 /* 190 * Prototypes for functions which OpenVPN plug-ins must define. 191 */ 192 193 /* 194 * FUNCTION: openvpn_plugin_open_v2 195 * 196 * REQUIRED: YES 197 * 198 * Called on initial plug-in load. OpenVPN will preserve plug-in state 199 * across SIGUSR1 restarts but not across SIGHUP restarts. A SIGHUP reset 200 * will cause the plugin to be closed and reopened. 201 * 202 * ARGUMENTS 203 * 204 * *type_mask : Set by OpenVPN to the logical OR of all script 205 * types which this version of OpenVPN supports. The plug-in 206 * should set this value to the logical OR of all script types 207 * which the plug-in wants to intercept. For example, if the 208 * script wants to intercept the client-connect and 209 * client-disconnect script types: 210 * 211 * *type_mask = OPENVPN_PLUGIN_MASK(OPENVPN_PLUGIN_CLIENT_CONNECT) 212 * | OPENVPN_PLUGIN_MASK(OPENVPN_PLUGIN_CLIENT_DISCONNECT) 213 * 214 * argv : a NULL-terminated array of options provided to the OpenVPN 215 * "plug-in" directive. argv[0] is the dynamic library pathname. 216 * 217 * envp : a NULL-terminated array of OpenVPN-set environmental 218 * variables in "name=value" format. Note that for security reasons, 219 * these variables are not actually written to the "official" 220 * environmental variable store of the process. 221 * 222 * return_list : used to return data back to OpenVPN. 223 * 224 * RETURN VALUE 225 * 226 * An openvpn_plugin_handle_t value on success, NULL on failure 227 */ 228 OPENVPN_PLUGIN_DEF openvpn_plugin_handle_t OPENVPN_PLUGIN_FUNC(openvpn_plugin_open_v2) 229 (unsigned int *type_mask, 230 const char *argv[], 231 const char *envp[], 232 struct openvpn_plugin_string_list **return_list); 233 234 /* 235 * FUNCTION: openvpn_plugin_func_v2 236 * 237 * Called to perform the work of a given script type. 238 * 239 * REQUIRED: YES 240 * 241 * ARGUMENTS 242 * 243 * handle : the openvpn_plugin_handle_t value which was returned by 244 * openvpn_plugin_open. 245 * 246 * type : one of the PLUGIN_x types 247 * 248 * argv : a NULL-terminated array of "command line" options which 249 * would normally be passed to the script. argv[0] is the dynamic 250 * library pathname. 251 * 252 * envp : a NULL-terminated array of OpenVPN-set environmental 253 * variables in "name=value" format. Note that for security reasons, 254 * these variables are not actually written to the "official" 255 * environmental variable store of the process. 256 * 257 * per_client_context : the per-client context pointer which was returned by 258 * openvpn_plugin_client_constructor_v1, if defined. 259 * 260 * return_list : used to return data back to OpenVPN. 261 * 262 * RETURN VALUE 263 * 264 * OPENVPN_PLUGIN_FUNC_SUCCESS on success, OPENVPN_PLUGIN_FUNC_ERROR on failure 265 * 266 * In addition, OPENVPN_PLUGIN_FUNC_DEFERRED may be returned by 267 * OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY. This enables asynchronous 268 * authentication where the plugin (or one of its agents) may indicate 269 * authentication success/failure some number of seconds after the return 270 * of the OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY handler by writing a single 271 * char to the file named by auth_control_file in the environmental variable 272 * list (envp). 273 * 274 * first char of auth_control_file: 275 * '0' -- indicates auth failure 276 * '1' -- indicates auth success 277 * 278 * OpenVPN will delete the auth_control_file after it goes out of scope. 279 * 280 * If an OPENVPN_PLUGIN_ENABLE_PF handler is defined and returns success 281 * for a particular client instance, packet filtering will be enabled for that 282 * instance. OpenVPN will then attempt to read the packet filter configuration 283 * from the temporary file named by the environmental variable pf_file. This 284 * file may be generated asynchronously and may be dynamically updated during the 285 * client session, however the client will be blocked from sending or receiving 286 * VPN tunnel packets until the packet filter file has been generated. OpenVPN 287 * will periodically test the packet filter file over the life of the client 288 * instance and reload when modified. OpenVPN will delete the packet filter file 289 * when the client instance goes out of scope. 290 * 291 * Packet filter file grammar: 292 * 293 * [CLIENTS DROP|ACCEPT] 294 * {+|-}common_name1 295 * {+|-}common_name2 296 * . . . 297 * [SUBNETS DROP|ACCEPT] 298 * {+|-}subnet1 299 * {+|-}subnet2 300 * . . . 301 * [END] 302 * 303 * Subnet: IP-ADDRESS | IP-ADDRESS/NUM_NETWORK_BITS 304 * 305 * CLIENTS refers to the set of clients (by their common-name) which 306 * this instance is allowed ('+') to connect to, or is excluded ('-') 307 * from connecting to. Note that in the case of client-to-client 308 * connections, such communication must be allowed by the packet filter 309 * configuration files of both clients. 310 * 311 * SUBNETS refers to IP addresses or IP address subnets which this 312 * instance may connect to ('+') or is excluded ('-') from connecting 313 * to. 314 * 315 * DROP or ACCEPT defines default policy when there is no explicit match 316 * for a common-name or subnet. The [END] tag must exist. A special 317 * purpose tag called [KILL] will immediately kill the client instance. 318 * A given client or subnet rule applies to both incoming and outgoing 319 * packets. 320 * 321 * See plugin/defer/simple.c for an example on using asynchronous 322 * authentication and client-specific packet filtering. 323 */ 324 OPENVPN_PLUGIN_DEF int OPENVPN_PLUGIN_FUNC(openvpn_plugin_func_v2) 325 (openvpn_plugin_handle_t handle, 326 const int type, 327 const char *argv[], 328 const char *envp[], 329 void *per_client_context, 330 struct openvpn_plugin_string_list **return_list); 331 332 /* 333 * FUNCTION: openvpn_plugin_close_v1 334 * 335 * REQUIRED: YES 336 * 337 * ARGUMENTS 338 * 339 * handle : the openvpn_plugin_handle_t value which was returned by 340 * openvpn_plugin_open. 341 * 342 * Called immediately prior to plug-in unload. 343 */ 344 OPENVPN_PLUGIN_DEF void OPENVPN_PLUGIN_FUNC(openvpn_plugin_close_v1) 345 (openvpn_plugin_handle_t handle); 346 347 /* 348 * FUNCTION: openvpn_plugin_abort_v1 349 * 350 * REQUIRED: NO 351 * 352 * ARGUMENTS 353 * 354 * handle : the openvpn_plugin_handle_t value which was returned by 355 * openvpn_plugin_open. 356 * 357 * Called when OpenVPN is in the process of aborting due to a fatal error. 358 * Will only be called on an open context returned by a prior successful 359 * openvpn_plugin_open callback. 360 */ 361 OPENVPN_PLUGIN_DEF void OPENVPN_PLUGIN_FUNC(openvpn_plugin_abort_v1) 362 (openvpn_plugin_handle_t handle); 363 364 /* 365 * FUNCTION: openvpn_plugin_client_constructor_v1 366 * 367 * Called to allocate a per-client memory region, which 368 * is then passed to the openvpn_plugin_func_v2 function. 369 * This function is called every time the OpenVPN server 370 * constructs a client instance object, which normally 371 * occurs when a session-initiating packet is received 372 * by a new client, even before the client has authenticated. 373 * 374 * This function should allocate the private memory needed 375 * by the plugin to track individual OpenVPN clients, and 376 * return a void * to this memory region. 377 * 378 * REQUIRED: NO 379 * 380 * ARGUMENTS 381 * 382 * handle : the openvpn_plugin_handle_t value which was returned by 383 * openvpn_plugin_open. 384 * 385 * RETURN VALUE 386 * 387 * void * pointer to plugin's private per-client memory region, or NULL 388 * if no memory region is required. 389 */ 390 OPENVPN_PLUGIN_DEF void * OPENVPN_PLUGIN_FUNC(openvpn_plugin_client_constructor_v1) 391 (openvpn_plugin_handle_t handle); 392 393 /* 394 * FUNCTION: openvpn_plugin_client_destructor_v1 395 * 396 * This function is called on client instance object destruction. 397 * 398 * REQUIRED: NO 399 * 400 * ARGUMENTS 401 * 402 * handle : the openvpn_plugin_handle_t value which was returned by 403 * openvpn_plugin_open. 404 * 405 * per_client_context : the per-client context pointer which was returned by 406 * openvpn_plugin_client_constructor_v1, if defined. 407 */ 408 OPENVPN_PLUGIN_DEF void OPENVPN_PLUGIN_FUNC(openvpn_plugin_client_destructor_v1) 409 (openvpn_plugin_handle_t handle, void *per_client_context); 410 411 /* 412 * FUNCTION: openvpn_plugin_select_initialization_point_v1 413 * 414 * Several different points exist in OpenVPN's initialization sequence where 415 * the openvpn_plugin_open function can be called. While the default is 416 * OPENVPN_PLUGIN_INIT_PRE_DAEMON, this function can be used to select a 417 * different initialization point. For example, if your plugin needs to 418 * return configuration parameters to OpenVPN, use 419 * OPENVPN_PLUGIN_INIT_PRE_CONFIG_PARSE. 420 * 421 * REQUIRED: NO 422 * 423 * RETURN VALUE: 424 * 425 * An OPENVPN_PLUGIN_INIT_x value. 426 */ 427 #define OPENVPN_PLUGIN_INIT_PRE_CONFIG_PARSE 1 428 #define OPENVPN_PLUGIN_INIT_PRE_DAEMON 2 /* default */ 429 #define OPENVPN_PLUGIN_INIT_POST_DAEMON 3 430 #define OPENVPN_PLUGIN_INIT_POST_UID_CHANGE 4 431 432 OPENVPN_PLUGIN_DEF int OPENVPN_PLUGIN_FUNC(openvpn_plugin_select_initialization_point_v1) 433 (void); 434 435 /* 436 * FUNCTION: openvpn_plugin_min_version_required_v1 437 * 438 * This function is called by OpenVPN to query the minimum 439 plugin interface version number required by the plugin. 440 * 441 * REQUIRED: NO 442 * 443 * RETURN VALUE 444 * 445 * The minimum OpenVPN plugin interface version number necessary to support 446 * this plugin. 447 */ 448 OPENVPN_PLUGIN_DEF int OPENVPN_PLUGIN_FUNC(openvpn_plugin_min_version_required_v1) 449 (void); 450 451 /* 452 * Deprecated functions which are still supported for backward compatibility. 453 */ 454 455 OPENVPN_PLUGIN_DEF openvpn_plugin_handle_t OPENVPN_PLUGIN_FUNC(openvpn_plugin_open_v1) 456 (unsigned int *type_mask, 457 const char *argv[], 458 const char *envp[]); 459 460 OPENVPN_PLUGIN_DEF int OPENVPN_PLUGIN_FUNC(openvpn_plugin_func_v1) 461 (openvpn_plugin_handle_t handle, const int type, const char *argv[], const char *envp[]); 462