OpenVPN
Data Structures | Macros | Typedefs | Enumerations | Functions
openvpn-plugin.h File Reference
#include <openssl/x509.h>
#include <stdarg.h>
#include <stddef.h>
Include dependency graph for openvpn-plugin.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  openvpn_plugin_string_list
 
struct  openvpn_plugin_callbacks
 Used by the openvpn_plugin_open_v3() function to pass callback function pointers to the plug-in. More...
 
struct  openvpn_plugin_args_open_in
 Arguments used to transport variables to the plug-in. More...
 
struct  openvpn_plugin_args_open_return
 Arguments used to transport variables from the plug-in back to the OpenVPN process. More...
 
struct  openvpn_plugin_args_func_in
 Arguments used to transport variables to and from the plug-in. More...
 
struct  openvpn_plugin_args_func_return
 Arguments used to transport variables to and from the plug-in. More...
 

Macros

#define OPENVPN_PLUGIN_VERSION   3
 
#define __OPENVPN_X509_CERT_T_DECLARED
 
#define OPENVPN_VERSION_MAJOR   2
 
#define OPENVPN_VERSION_MINOR   5
 
#define OPENVPN_VERSION_PATCH   "_git"
 
#define OPENVPN_PLUGIN_UP   0
 
#define OPENVPN_PLUGIN_DOWN   1
 
#define OPENVPN_PLUGIN_ROUTE_UP   2
 
#define OPENVPN_PLUGIN_IPCHANGE   3
 
#define OPENVPN_PLUGIN_TLS_VERIFY   4
 
#define OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY   5
 
#define OPENVPN_PLUGIN_CLIENT_CONNECT   6
 
#define OPENVPN_PLUGIN_CLIENT_DISCONNECT   7
 
#define OPENVPN_PLUGIN_LEARN_ADDRESS   8
 
#define OPENVPN_PLUGIN_CLIENT_CONNECT_V2   9
 
#define OPENVPN_PLUGIN_TLS_FINAL   10
 
#define OPENVPN_PLUGIN_ENABLE_PF   11
 
#define OPENVPN_PLUGIN_ROUTE_PREDOWN   12
 
#define OPENVPN_PLUGIN_N   13
 
#define OPENVPN_PLUGIN_MASK(x)   (1<<(x))
 
#define OPENVPN_PLUGIN_FUNC_SUCCESS   0
 
#define OPENVPN_PLUGIN_FUNC_ERROR   1
 
#define OPENVPN_PLUGIN_FUNC_DEFERRED   2
 
#define OPENVPN_EXPORT   __declspec(dllexport)
 
#define OPENVPN_PLUGIN_DEF   OPENVPN_EXPORT
 
#define OPENVPN_PLUGIN_FUNC(name)   name
 
#define OPENVPN_PLUGINv3_STRUCTVER   4
 Defines version of the v3 plugin argument structs. More...
 
#define _ovpn_chk_fmt(a, b)
 
#define OPENVPN_PLUGIN_INIT_PRE_CONFIG_PARSE   1
 
#define OPENVPN_PLUGIN_INIT_PRE_DAEMON   2 /* default */
 
#define OPENVPN_PLUGIN_INIT_POST_DAEMON   3
 
#define OPENVPN_PLUGIN_INIT_POST_UID_CHANGE   4
 

Typedefs

typedef X509 openvpn_x509_cert_t
 
typedef void * openvpn_plugin_handle_t
 
typedef void(* plugin_log_t) (openvpn_plugin_log_flags_t flags, const char *plugin_name, const char *format,...) _ovpn_chk_fmt(3
 
typedef void(*) typedef void(* plugin_vlog_t) (openvpn_plugin_log_flags_t flags, const char *plugin_name, const char *format, va_list arglist) _ovpn_chk_fmt(3
 
typedef void(*) typedef void(*) typedef void(* plugin_secure_memzero_t) (void *data, size_t len)
 Export of secure_memzero() to be used inside plug-ins. More...
 

Enumerations

enum  openvpn_plugin_log_flags_t {
  PLOG_ERR = (1 << 0), PLOG_WARN = (1 << 1), PLOG_NOTE = (1 << 2), PLOG_DEBUG = (1 << 3),
  PLOG_ERRNO = (1 << 8), PLOG_NOMUTE = (1 << 9)
}
 Definitions needed for the plug-in callback functions. More...
 
enum  ovpnSSLAPI { SSLAPI_NONE, SSLAPI_OPENSSL, SSLAPI_MBEDTLS }
 Used by the openvpn_plugin_open_v3() function to indicate to the plug-in what kind of SSL implementation OpenVPN uses. More...
 

Functions

OPENVPN_PLUGIN_DEF openvpn_plugin_handle_t OPENVPN_PLUGIN_FUNC() openvpn_plugin_open_v2 (unsigned int *type_mask, const char *argv[], const char *envp[], struct openvpn_plugin_string_list **return_list)
 
OPENVPN_PLUGIN_DEF int OPENVPN_PLUGIN_FUNC() openvpn_plugin_func_v2 (openvpn_plugin_handle_t handle, const int type, const char *argv[], const char *envp[], void *per_client_context, struct openvpn_plugin_string_list **return_list)
 
OPENVPN_PLUGIN_DEF int OPENVPN_PLUGIN_FUNC() openvpn_plugin_open_v3 (const int version, struct openvpn_plugin_args_open_in const *arguments, struct openvpn_plugin_args_open_return *retptr)
 This function is called when OpenVPN loads the plug-in. More...
 
OPENVPN_PLUGIN_DEF int OPENVPN_PLUGIN_FUNC() openvpn_plugin_func_v3 (const int version, struct openvpn_plugin_args_func_in const *arguments, struct openvpn_plugin_args_func_return *retptr)
 
OPENVPN_PLUGIN_DEF void OPENVPN_PLUGIN_FUNC() openvpn_plugin_close_v1 (openvpn_plugin_handle_t handle)
 This cleans up the last part of the plug-in, allows it to shut down cleanly and release the plug-in global context buffer. More...
 
OPENVPN_PLUGIN_DEF void OPENVPN_PLUGIN_FUNC() openvpn_plugin_abort_v1 (openvpn_plugin_handle_t handle)
 
OPENVPN_PLUGIN_DEF void *OPENVPN_PLUGIN_FUNC() openvpn_plugin_client_constructor_v1 (openvpn_plugin_handle_t handle)
 
OPENVPN_PLUGIN_DEF void OPENVPN_PLUGIN_FUNC() openvpn_plugin_client_destructor_v1 (openvpn_plugin_handle_t handle, void *per_client_context)
 
OPENVPN_PLUGIN_DEF int OPENVPN_PLUGIN_FUNC() openvpn_plugin_select_initialization_point_v1 (void)
 
OPENVPN_PLUGIN_DEF int OPENVPN_PLUGIN_FUNC() openvpn_plugin_min_version_required_v1 (void)
 
OPENVPN_PLUGIN_DEF openvpn_plugin_handle_t OPENVPN_PLUGIN_FUNC() openvpn_plugin_open_v1 (unsigned int *type_mask, const char *argv[], const char *envp[])
 
OPENVPN_PLUGIN_DEF int OPENVPN_PLUGIN_FUNC() openvpn_plugin_func_v1 (openvpn_plugin_handle_t handle, const int type, const char *argv[], const char *envp[])
 This function is called by OpenVPN each time the OpenVPN reaches a point where plug-in calls should happen. More...
 

Macro Definition Documentation

◆ __OPENVPN_X509_CERT_T_DECLARED

#define __OPENVPN_X509_CERT_T_DECLARED

Definition at line 39 of file openvpn-plugin.h.

◆ _ovpn_chk_fmt

#define _ovpn_chk_fmt (   a,
 
)

Definition at line 249 of file openvpn-plugin.h.

◆ OPENVPN_EXPORT

#define OPENVPN_EXPORT   __declspec(dllexport)

◆ OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY

#define OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY   5

◆ OPENVPN_PLUGIN_CLIENT_CONNECT

#define OPENVPN_PLUGIN_CLIENT_CONNECT   6

Definition at line 126 of file openvpn-plugin.h.

Referenced by multi_connection_established(), and plugin_type_name().

◆ OPENVPN_PLUGIN_CLIENT_CONNECT_V2

#define OPENVPN_PLUGIN_CLIENT_CONNECT_V2   9

◆ OPENVPN_PLUGIN_CLIENT_DISCONNECT

#define OPENVPN_PLUGIN_CLIENT_DISCONNECT   7

◆ OPENVPN_PLUGIN_DEF

#define OPENVPN_PLUGIN_DEF   OPENVPN_EXPORT

Definition at line 179 of file openvpn-plugin.h.

◆ OPENVPN_PLUGIN_DOWN

#define OPENVPN_PLUGIN_DOWN   1

◆ OPENVPN_PLUGIN_ENABLE_PF

#define OPENVPN_PLUGIN_ENABLE_PF   11

◆ OPENVPN_PLUGIN_FUNC

#define OPENVPN_PLUGIN_FUNC (   name)    name

Definition at line 180 of file openvpn-plugin.h.

◆ OPENVPN_PLUGIN_FUNC_DEFERRED

#define OPENVPN_PLUGIN_FUNC_DEFERRED   2

◆ OPENVPN_PLUGIN_FUNC_ERROR

#define OPENVPN_PLUGIN_FUNC_ERROR   1

◆ OPENVPN_PLUGIN_FUNC_SUCCESS

#define OPENVPN_PLUGIN_FUNC_SUCCESS   0

◆ OPENVPN_PLUGIN_INIT_POST_DAEMON

#define OPENVPN_PLUGIN_INIT_POST_DAEMON   3

Definition at line 802 of file openvpn-plugin.h.

Referenced by init_instance().

◆ OPENVPN_PLUGIN_INIT_POST_UID_CHANGE

#define OPENVPN_PLUGIN_INIT_POST_UID_CHANGE   4

Definition at line 803 of file openvpn-plugin.h.

Referenced by init_instance().

◆ OPENVPN_PLUGIN_INIT_PRE_CONFIG_PARSE

#define OPENVPN_PLUGIN_INIT_PRE_CONFIG_PARSE   1

Definition at line 800 of file openvpn-plugin.h.

Referenced by openvpn_main().

◆ OPENVPN_PLUGIN_INIT_PRE_DAEMON

#define OPENVPN_PLUGIN_INIT_PRE_DAEMON   2 /* default */

Definition at line 801 of file openvpn-plugin.h.

Referenced by init_instance(), and plugin_init_item().

◆ OPENVPN_PLUGIN_IPCHANGE

#define OPENVPN_PLUGIN_IPCHANGE   3

◆ OPENVPN_PLUGIN_LEARN_ADDRESS

#define OPENVPN_PLUGIN_LEARN_ADDRESS   8

◆ OPENVPN_PLUGIN_MASK

#define OPENVPN_PLUGIN_MASK (   x)    (1<<(x))

◆ OPENVPN_PLUGIN_N

#define OPENVPN_PLUGIN_N   13

Definition at line 133 of file openvpn-plugin.h.

Referenced by plugin_mask_string(), and plugin_supported_types().

◆ OPENVPN_PLUGIN_ROUTE_PREDOWN

#define OPENVPN_PLUGIN_ROUTE_PREDOWN   12

Definition at line 132 of file openvpn-plugin.h.

Referenced by do_close_tun(), and plugin_type_name().

◆ OPENVPN_PLUGIN_ROUTE_UP

#define OPENVPN_PLUGIN_ROUTE_UP   2

◆ OPENVPN_PLUGIN_TLS_FINAL

#define OPENVPN_PLUGIN_TLS_FINAL   10

◆ OPENVPN_PLUGIN_TLS_VERIFY

#define OPENVPN_PLUGIN_TLS_VERIFY   4

◆ OPENVPN_PLUGIN_UP

#define OPENVPN_PLUGIN_UP   0

◆ OPENVPN_PLUGIN_VERSION

#define OPENVPN_PLUGIN_VERSION   3

Definition at line 28 of file openvpn-plugin.h.

Referenced by plugin_init_item().

◆ OPENVPN_PLUGINv3_STRUCTVER

#define OPENVPN_PLUGINv3_STRUCTVER   4

Defines version of the v3 plugin argument structs.

Whenever one or more of these structs are modified, this constant must be updated. A changelog should be appended in this comment as well, to make it easier to see what information is available in the different versions.

Version Comment 1 Initial plugin v3 structures providing the same API as the v2 plugin interface, X509 certificate information + a logging API for plug-ins.

2 Added ssl_api member in struct openvpn_plugin_args_open_in which identifies the SSL implementation OpenVPN is compiled against.

3 Added ovpn_version, ovpn_version_major, ovpn_version_minor and ovpn_version_patch to provide the runtime version of OpenVPN to plug-ins.

4 Exported secure_memzero() as plugin_secure_memzero()

Definition at line 224 of file openvpn-plugin.h.

Referenced by openvpn_plugin_open_v3(), plugin_call_item(), and plugin_open_item().

◆ OPENVPN_VERSION_MAJOR

#define OPENVPN_VERSION_MAJOR   2

Definition at line 54 of file openvpn-plugin.h.

◆ OPENVPN_VERSION_MINOR

#define OPENVPN_VERSION_MINOR   5

Definition at line 55 of file openvpn-plugin.h.

◆ OPENVPN_VERSION_PATCH

#define OPENVPN_VERSION_PATCH   "_git"

Definition at line 56 of file openvpn-plugin.h.

Typedef Documentation

◆ openvpn_plugin_handle_t

typedef void* openvpn_plugin_handle_t

Definition at line 144 of file openvpn-plugin.h.

◆ openvpn_x509_cert_t

typedef X509 openvpn_x509_cert_t

Definition at line 40 of file openvpn-plugin.h.

◆ plugin_log_t

typedef void(* plugin_log_t) (openvpn_plugin_log_flags_t flags, const char *plugin_name, const char *format,...) _ovpn_chk_fmt(3

Definition at line 252 of file openvpn-plugin.h.

◆ plugin_secure_memzero_t

typedef void(*) typedef void(*) typedef void(* plugin_secure_memzero_t) (void *data, size_t len)

Export of secure_memzero() to be used inside plug-ins.

Parameters
dataPointer to data to zeroise
lenLength of data, in bytes

Definition at line 269 of file openvpn-plugin.h.

◆ plugin_vlog_t

typedef void(*) typedef void(* plugin_vlog_t) (openvpn_plugin_log_flags_t flags, const char *plugin_name, const char *format, va_list arglist) _ovpn_chk_fmt(3

Definition at line 256 of file openvpn-plugin.h.

Enumeration Type Documentation

◆ openvpn_plugin_log_flags_t

Definitions needed for the plug-in callback functions.

Enumerator
PLOG_ERR 
PLOG_WARN 
PLOG_NOTE 
PLOG_DEBUG 
PLOG_ERRNO 
PLOG_NOMUTE 

Definition at line 229 of file openvpn-plugin.h.

◆ ovpnSSLAPI

enum ovpnSSLAPI

Used by the openvpn_plugin_open_v3() function to indicate to the plug-in what kind of SSL implementation OpenVPN uses.

This is to avoid SEGV issues when OpenVPN is complied against mbed TLS and the plug-in against OpenSSL.

Enumerator
SSLAPI_NONE 
SSLAPI_OPENSSL 
SSLAPI_MBEDTLS 

Definition at line 301 of file openvpn-plugin.h.

Function Documentation

◆ openvpn_plugin_abort_v1()

OPENVPN_PLUGIN_DEF void OPENVPN_PLUGIN_FUNC() openvpn_plugin_abort_v1 ( openvpn_plugin_handle_t  handle)

◆ openvpn_plugin_client_constructor_v1()

OPENVPN_PLUGIN_DEF void* OPENVPN_PLUGIN_FUNC() openvpn_plugin_client_constructor_v1 ( openvpn_plugin_handle_t  handle)

Definition at line 320 of file simple.c.

References OPENVPN_EXPORT, and ovpn_note.

◆ openvpn_plugin_client_destructor_v1()

OPENVPN_PLUGIN_DEF void OPENVPN_PLUGIN_FUNC() openvpn_plugin_client_destructor_v1 ( openvpn_plugin_handle_t  handle,
void *  per_client_context 
)

Definition at line 327 of file simple.c.

References free, session::key, OPENVPN_EXPORT, and ovpn_note.

◆ openvpn_plugin_close_v1()

OPENVPN_PLUGIN_DEF void OPENVPN_PLUGIN_FUNC() openvpn_plugin_close_v1 ( openvpn_plugin_handle_t  handle)

This cleans up the last part of the plug-in, allows it to shut down cleanly and release the plug-in global context buffer.

Parameters
handlePointer to the plug-in global context buffer, which need to be released by this function

Definition at line 334 of file simple.c.

References down_root_context::background_pid, auth_pam_context::background_pid, COMMAND_EXIT, DEBUG, down_root_context::foreground_fd, auth_pam_context::foreground_fd, free, free_context(), OPENVPN_EXPORT, send_control(), down_root_context::verb, and auth_pam_context::verb.

◆ openvpn_plugin_func_v1()

OPENVPN_PLUGIN_DEF int OPENVPN_PLUGIN_FUNC() openvpn_plugin_func_v1 ( openvpn_plugin_handle_t  handle,
const int  type,
const char *  argv[],
const char *  envp[] 
)

This function is called by OpenVPN each time the OpenVPN reaches a point where plug-in calls should happen.

It only happens for those plug-in hooks enabled in openvpn_plugin_open_v3().

For the arguments, see the include/openvpn-plugin.h file for details on the function parameters

Parameters
argsPointer to a struct with details about the plug-in call from the main OpenVPN process.
returndataPointer to a struct where the plug-in can provide information back to OpenVPN to be processed
Returns
Must return OPENVPN_PLUGIN_FUNC_SUCCESS or OPENVPN_PLUGIN_FUNC_DEFERRED on success. Otherwise it should return OPENVPN_FUNC_ERROR, which will stop and reject the client session from progressing.

Definition at line 171 of file log.c.

References down_root_context::background_pid, close_fds_except(), down_root_context::command, COMMAND_RUN_SCRIPT, COMMAND_VERIFY, daemonize(), down_root_server(), down_root_context::foreground_fd, auth_pam_context::foreground_fd, free, get_env(), OPENVPN_EXPORT, OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY, OPENVPN_PLUGIN_CLIENT_CONNECT_V2, OPENVPN_PLUGIN_DOWN, OPENVPN_PLUGIN_FUNC_ERROR, OPENVPN_PLUGIN_FUNC_SUCCESS, OPENVPN_PLUGIN_TLS_VERIFY, OPENVPN_PLUGIN_UP, ovpn_base64_decode, ovpn_base64_encode, ovpn_log, plugin_context::password, PLOG_ERR, PLOG_NOTE, PLUGIN_NAME, recv_control(), RESPONSE_INIT_SUCCEEDED, RESPONSE_SCRIPT_SUCCEEDED, RESPONSE_VERIFY_SUCCEEDED, send_control(), send_string(), set_signals(), show(), status, plugin_context::username, and down_root_context::verb.

◆ openvpn_plugin_func_v2()

OPENVPN_PLUGIN_DEF int OPENVPN_PLUGIN_FUNC() openvpn_plugin_func_v2 ( openvpn_plugin_handle_t  handle,
const int  type,
const char *  argv[],
const char *  envp[],
void *  per_client_context,
struct openvpn_plugin_string_list **  return_list 
)

◆ openvpn_plugin_func_v3()

OPENVPN_PLUGIN_DEF int OPENVPN_PLUGIN_FUNC() openvpn_plugin_func_v3 ( const int  version,
struct openvpn_plugin_args_func_in const *  arguments,
struct openvpn_plugin_args_func_return retptr 
)

◆ openvpn_plugin_min_version_required_v1()

OPENVPN_PLUGIN_DEF int OPENVPN_PLUGIN_FUNC() openvpn_plugin_min_version_required_v1 ( void  )

◆ openvpn_plugin_open_v1()

OPENVPN_PLUGIN_DEF openvpn_plugin_handle_t OPENVPN_PLUGIN_FUNC() openvpn_plugin_open_v1 ( unsigned int *  type_mask,
const char *  argv[],
const char *  envp[] 
)

◆ openvpn_plugin_open_v2()

OPENVPN_PLUGIN_DEF openvpn_plugin_handle_t OPENVPN_PLUGIN_FUNC() openvpn_plugin_open_v2 ( unsigned int *  type_mask,
const char *  argv[],
const char *  envp[],
struct openvpn_plugin_string_list **  return_list 
)

◆ openvpn_plugin_open_v3()

OPENVPN_PLUGIN_DEF int OPENVPN_PLUGIN_FUNC() openvpn_plugin_open_v3 ( const int  v3structver,
struct openvpn_plugin_args_open_in const *  args,
struct openvpn_plugin_args_open_return ret 
)

This function is called when OpenVPN loads the plug-in.

The purpose is to initialize the plug-in and tell OpenVPN which plug-in hooks this plug-in wants to be involved in

For the arguments, see the include/openvpn-plugin.h file for details on the function parameters

Parameters
v3structverAn integer containing the API version of the plug-in structs OpenVPN uses
argsA pointer to the argument struct for information and features provided by OpenVPN to the plug-in
retA pointer to the struct OpenVPN uses to receive information back from the plug-in
Returns
Must return OPENVPN_PLUGIN_FUNC_SUCCESS when everything completed successfully. Otherwise it must be returned OPENVPN_PLUGIN_FUNC_ERROR, which will stop OpenVPN from running

Definition at line 89 of file keyingmaterialexporter.c.

References openvpn_plugin_args_open_in::argv, auth_pam_context::background_pid, openvpn_plugin_args_open_in::callbacks, CLIENT, close_fds_except(), daemonize(), name_value_list::data, openvpn_plugin_args_open_in::envp, auth_pam_context::foreground_fd, free, get_env(), openvpn_plugin_args_open_return::handle, name_value_list::len, plugin::log, plugin::mask, N_NAME_VALUE, name_value::name, OPENVPN_EXPORT, OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY, OPENVPN_PLUGIN_CLIENT_CONNECT_V2, OPENVPN_PLUGIN_CLIENT_DISCONNECT, OPENVPN_PLUGIN_DOWN, OPENVPN_PLUGIN_FUNC_ERROR, OPENVPN_PLUGIN_FUNC_SUCCESS, OPENVPN_PLUGIN_IPCHANGE, OPENVPN_PLUGIN_LEARN_ADDRESS, OPENVPN_PLUGIN_MASK, OPENVPN_PLUGIN_ROUTE_UP, OPENVPN_PLUGIN_TLS_FINAL, OPENVPN_PLUGIN_TLS_VERIFY, OPENVPN_PLUGIN_UP, OPENVPN_PLUGINv3_STRUCTVER, ovpn_base64_decode, ovpn_base64_encode, ovpn_log, ovpn_note, openvpn_plugin_args_open_in::ovpn_version, openvpn_plugin_args_open_in::ovpn_version_major, openvpn_plugin_args_open_in::ovpn_version_minor, openvpn_plugin_args_open_in::ovpn_version_patch, ovpn_vlog, pam_server(), plugin_context::password, PLOG_NOTE, plugin_base64_decode, openvpn_plugin_callbacks::plugin_log, PLUGIN_NAME, plugin_secure_memzero, openvpn_plugin_callbacks::plugin_secure_memzero, openvpn_plugin_callbacks::plugin_vlog, recv_control(), RESPONSE_INIT_SUCCEEDED, SERVER, set_signals(), openvpn_plugin_args_open_in::ssl_api, SSLAPI_OPENSSL, status, string_array_len(), plugin::type, openvpn_plugin_args_open_return::type_mask, plugin_context::username, name_value::value, and auth_pam_context::verb.

◆ openvpn_plugin_select_initialization_point_v1()

OPENVPN_PLUGIN_DEF int OPENVPN_PLUGIN_FUNC() openvpn_plugin_select_initialization_point_v1 ( void  )